A field guide

How Ghostli Works

A practical look at the workspace, the access model, and the request path - written for the developers who would rather read the manual than guess.

Ghostli · Privacy & Architecture Notes

Ghostli started with an unfashionable question: what does an AI workspace look like when the user is treated as a competent adult? Most tools in this category answer by adding more panels, more toggles, and more telemetry. We went the other way. We started by listing the things a serious developer would reasonably want from an assistant, then built the product around three boring, powerful ideas: minimize identity, make context explicit, and keep local work local until the user asks the assistant to use it.

What follows is a long-form read, not a feature list. It is still written like a product page because privacy should feel desirable, not medicinal. But the claims are intentionally concrete: token access, local encryption, capped workspace indexing, redacted server logs, in-memory uploads, and request context assembled only from the things that are actually relevant to the current task.

01 An idea worth keeping small

The product is a desktop workspace for working with frontier models on real code. It is not a chat client, although it can look like one, and it is not an IDE, although it lives close to one. The job Ghostli does well is the one in the middle: it keeps a small, deliberate amount of project context ready, lets you ask sharp questions about it, and stays out of the way while you work.

We made an early decision to keep the surface area narrow. There is one workspace, not many. There is one model picker, not a marketplace. There is one settings panel, and a surprising number of things in it are explanations rather than toggles. If you're used to products that grow by accretion, the first hour in Ghostli can feel sparse. That's on purpose.

"The product should make it obvious what it knows about you. If it can't be obvious, it shouldn't know."

The part technical users usually notice Ghostli is not trying to hide complexity behind a privacy slogan. The app splits identity, billing, device state, local storage, workspace scanning, and model context into separate layers. That separation is the privacy feature: each layer gets only the information it needs to do its job.

02 Where the workspace ends

The first thing to understand is the shape of the boundary between Ghostli and the rest of your machine. The workspace is a folder you choose. Everything inside that folder is, in principle, available to the assistant. Everything outside of it is, by default, invisible - not blocked, not redacted, simply not in scope.

This sounds like a small distinction, but it changes how the tool feels. You pick a directory, the workspace becomes the boundary, and you can move the boundary at any time by picking a different directory. If you want a tighter scope, pick a smaller folder. If you want a wider one, pick a larger one. The product tries very hard not to second-guess that choice.

Inside the workspace, Ghostli keeps two different kinds of local context. When you enable Live Workspace or Repository Context, the app scans the selected folder locally, skips heavy folders such as node_modules, .git, dist, build, caches, virtual environments, and binary-heavy assets, and builds a capped file list or preview index so the assistant can orient itself. It does not upload the whole project just because the app starts. Context is added to a request when a feature is enabled, when you attach files, or when workspace tools read/search exact files during the task.

That local context can be remembered with the session. If you reopen a session, Ghostli may restore the selected Live Workspace or Repository Context state from local app storage. The important boundary is practical: local scanning and cached file maps are not the same thing as remote cloud sync, and the prompt still receives only the selected previews, maps, search results, file reads, attachments, and conversation context needed for the request.

The workspace tools are also bounded before they become intelligent. File listing is capped, search results are capped, large reads return an overview or targeted range, and system or application directories are rejected by the local IPC layer. In practice, Ghostli tries to give the assistant a map, then forces it to ask for exact files before making exact claims or edits.

03 Tokens, checkout email, and the customer panel

Ghostli does not use a traditional app account. There is no username/password login for the desktop workspace, no public profile, and no cloud-synced settings page. The app unlocks access with an access token, and that token is what the desktop client presents when it talks to the access layer.

This does not mean Ghostli never processes an email address. Checkout and free-token claims may require a reachable email so a token can be delivered, payment status can be resolved, and abuse of free claims can be limited. That email belongs to the delivery and billing flow; it is not used as the identity the desktop app sends with ordinary model requests.

The customer panel is a separate token-management surface, not a full social account system. You open it from /customer/ and authenticate with the active access token that was issued after checkout or a free claim. The panel can be used for practical plan and token tasks, such as checking access state or requesting token rotation. If a token is revoked and reissued, the new token replaces the old one; the model request flow still uses the token, not an email/password profile.

In the desktop app, the token should be treated like an API key. Store it carefully, do not paste it into prompts, and rotate it if it appears in logs, screenshots, support messages, or a shared repository.

The precise distinction Ghostli minimizes app identity, not all operational processing. Payment providers, checkout sessions, free claim controls, token delivery, support, and abuse prevention may process limited operational data. Ordinary AI requests should not need your payment email, payment details, raw token, or classic account profile.

On the service side, access tokens are stored as bcrypt hashes rather than as raw reusable tokens. Requests are associated with a token hash and a device identifier for plan limits, active-device limits, heartbeat checks, daily usage accounting, and token rotation. Rate limits prefer the device identifier; when an IP-based key is needed, the server uses a runtime-salted hash instead of keeping the raw address as the rate-limit key. It is not magic anonymity, but it is a deliberate reduction of identity in the parts of the system that do not need identity.

04 Local, encrypted, and quiet

Anything Ghostli saves - conversation history, attached files, workspace metadata, the local index of the folder you're working in - lives in a single directory on your machine, in a structure we'll document publicly once it stabilizes. The default location is platform-native, and you can move it to an encrypted volume if you prefer.

Where the platform supports it, the database that holds this data is encrypted at rest using a key derived from a passphrase you set on first launch. Current builds use modern local key derivation where available, including Argon2id for authentication material with a PBKDF2 compatibility path, and AES-GCM for encrypted local packages. Losing the passphrase means losing the local data, by design.

The desktop auth session is stored through the operating system's secure storage when available, and the encrypted workspace/session package is stored locally. We do not have a cloud copy of your local conversation database, workspace cache, or encrypted local package. If your drive dies and you have no local backup, the data is gone. This is occasionally inconvenient; it is also the point.

05 Choosing what enters the request

The single most important thing Ghostli does, on a moment-to-moment basis, is decide what context goes into a request. Without workspace features, the model receives the conversation and the files or images you explicitly attach. With Live Workspace enabled, the prompt can include a capped folder map and a sample of known paths so the assistant can decide which exact files to inspect with tools. With Repository Context enabled, Ghostli can include a project map, manifest, selected previews, and relevance-ranked snippets from the folder you selected.

That means Ghostli is not a black-box sync engine, but it is also not limited to only the single file you typed about. The app uses local file lists, previews, search results, and session code memory to ground answers. That memory is built from tool outputs such as file reads, searches, directory listings, and successful mutations; it is not a silent full-repository upload. For edits, the stronger rule is still enforced in the Live Code prompt: the assistant should search or read exact files before changing them and should treat tool output as the verified source of truth.

This is the part of the product we expect to keep iterating on. Selection is the lever, and the UI should make the active workspace/context state visible. Predictability is the feature.

Why this feels different The impressive part is not that Ghostli can read a project. Many tools can. The impressive part is that it keeps the assistant on rails: first a bounded map, then targeted search, then exact file reads, then edits backed by tool results. Less guesswork, less accidental context, better answers.

06 How a prompt becomes a reply

When you press send, the request is assembled from the current conversation, the mode you enabled, and the context that mode is allowed to add. The exact shape varies: a normal chat request is small, Repository Context can add project maps and selected previews, and Live Code can add workspace maps, tool results, task memory, and session code retrieval memory.

The prompt is assembled. The conversation history is appended, selected attachments are included, and any enabled workspace context is added within capped budgets: folder maps, manifests, previews, snippets, search results, or exact file reads depending on the mode. Live Code may also include session memory built from earlier tool results.
The access layer checks the token. The service validates whether the token is allowed to make the request and applies plan limits, device/session state, heartbeat state, daily usage accounting, and abuse controls. The token is operational access data, and the stored server-side representation is a hash rather than the raw token itself.
The request is routed for model processing. The model request contains the prompt and selected context needed to generate the reply. Server logging is designed to redact content-bearing fields such as prompts, messages, history, file content, authorization values, tokens, secrets, and keys. File uploads are accepted into memory with size and extension limits, then sanitized before they become prompt context. If a workspace feature includes absolute paths, folder names, file maps, file contents, snippets, terminal output, or tool results in the prompt, that material can still be processed by the AI service; do not include workspace context you are not allowed to process with AI infrastructure.
The reply streams back and session state is updated locally. The response is shown in the app, conversation state is saved locally, and Live Code keeps an in-session action history, read cache, task memory, and session retrieval memory so follow-up tool work can stay grounded in previous tool results.

The practical audit trail today is the visible Live Code activity log plus the session's stored action history and tool results. It is useful for understanding what the assistant did, but it should not be described as a separate plain-text .ghostli/audit export unless that export exists in the shipped app.

07 What Ghostli intentionally does not do

It is easier to trust a tool that admits its limits, so we list them plainly:

It does not train Ghostli-owned models on your prompts, your code, or your replies.
It does not present the desktop workspace as a cloud-synced account with remote chat history or a remotely stored full-project index.
It does not need a classic username/password profile for normal app access.
It does not treat checkout email as model-request identity.
It does not keep raw access tokens as the normal server-side lookup value.
It does not use raw IP addresses as the preferred rate-limit key when a device identifier or anonymized runtime hash can be used instead.
It does not promise that AI requests are never processed by infrastructure or upstream providers; model output requires processing the prompt and selected context.

Some operational systems still exist because the service has to function: payment confirmation, free-token claim limits, usage counters, rate limits, abuse controls, support, and token delivery. The point is not to pretend those systems do not exist. The point is to keep them separated from the ordinary model request path wherever practical.

08 A workspace that gets out of the way

That is the whole shape of it. A folder, a token, a local encrypted store, a minimized access layer, visible workspace context, redacted operational logs, and tool results the assistant has to ground itself in. Everything else - the streaming UI, the model picker, the diff viewer, the pricing page - is decoration on top of those pieces.

If that sounds like a product you would like to use, the door is open. If it sounds like a product you would like to question, use the support channels listed in the Terms.