Configuration
Environment variables, the ~/.sprocket data directory, ports, and credential storage for the Sprocket server, CLI, and desktop app.
Environment variables
| Variable | Effect | Default |
|---|---|---|
SPROCKET_PORT | Port for the local server. The desktop app reads it too. | 17731 |
SPROCKET_HOST | Address the server listens on. | 127.0.0.1 |
SPROCKET_DATA_DIR | Data directory. The desktop app reads it too. | ~/.sprocket |
SPROCKET_DESKTOP_EXECUTABLE | Path to the desktop app that sprocket opens. | The path in desktop-executable |
RUST_LOG | Log filter, such as info or sprocket_host=debug. sprocket_server logs stay at errors only. | Errors only |
Data directory
Sprocket keeps its local state in ~/.sprocket on every OS. On Windows without HOME set, it uses %USERPROFILE%\.sprocket.
Each data directory is a separate profile with its own sign-in. Set SPROCKET_DATA_DIR to run a second profile.
| Path | Contents |
|---|---|
credentials/ | Your sign-in, when stored in a file |
transcripts/ | Cached thread transcripts, attachments, and command logs |
tools/ | Tools Sprocket installs for the agent |
connectors/ | Installed connectors, such as KiCad |
desktop-executable | Where the desktop app is, saved each time it starts |
cli-server.log | Log of the temporary server the CLI starts |
Transcript parts
This is only in dev and canary builds. It isn’t in a stable release yet. See release channels.
Transcript parts record prompts, model completions, and tool results. A completion’s tool-call item contains the tool’s name, input, and toolInvocationId. Its result has the same invocation ID, a terminal status (completed, failed, or cancelled), and output. A call without a result is still running. Reasoning and tool calls form work blocks until the next non-empty text item.
Older transcripts can also contain started tool parts and work-section metadata. Current readers ignore the started parts and derive blocks from item order. Those parts keep their original numbers.
Transcript files
This is only in dev and canary builds. It isn’t in a stable release yet. See release channels.
Thread files live in transcripts/<user-id>/<thread-id>/:
| Path | Contents |
|---|---|
parts/00000000.jsonl | Parts 0-99, sorted by number. Filenames start each 100-part range. |
attachments/ | Downloaded and uploaded attachments, with their metadata. |
command-logs/ | Command output and session details. |
Convex holds the full transcript. Sprocket caches recent parts first and downloads older parts while the thread is open in a tab or an agent is running. Closing the last tab stops background downloads unless a run is still active.
From the thread directory, cat parts/*.jsonl reads cached parts in order. The cache can have gaps while older history downloads.
After upgrading, the first open of a thread replaces its old transcript cache, including SQLite and state.json. Attachments and command logs are preserved.
Credentials
Sprocket stores your sign-in in the OS keyring when one is available. Otherwise it falls back to an unencrypted file in the data directory that only your user can read, and sprocket login tells you so.
To choose the store yourself:
sprocket logout
sprocket login --credential-store keyringUse --credential-store file to always use the file. Choosing one store clears the other.