Configuration

Everything sharedcode knows lives in one directory, by default ~/.sharedcode/. There is no database server and no hidden state elsewhere. Back up that directory and you have backed up your agents, your sessions and your memory.

The home directory

The root is chosen in this order:

1. The parent of SHAREDCODE_AGENTS_HOME, if that is set.
2. SHAREDCODE_HOME, if that is set. sharedcode-serve requires an absolute path here.
3. ~/.sharedcode.

After the Quickstart, the tree looked like this (one entry per kind; the sessions/ directory held one file per session):

Path	What it is
config.json	Global configuration: models, skills, endpoints. Every save also writes a timestamped config.json.bak.<time>; the newest ten are kept.
agents/<name>/config.json	One agent: engine, profile, permission mode, tool allowlist.
agents/<name>/AGENTS.md	That agent's instructions.
secrets.env, agents/<name>/secrets.env	API keys as NAME=value lines. The per-agent file overrides the shared one. Neither exists until you create it.
sessions/<session_id>.jsonl	The session ledger: one append-only file per session. This is the source of truth.
sessions/sessions.db	SQLite cache of the ledgers, rebuildable with sharedcode session rebuild.
usage/ledger.db	Per-call token, timing and cost records.
goals/, loops/	Goal and scheduled-loop state.
web/sessions.db	Web UI accounts and sign-in sessions.
.env	The web UI's session secret, generated on first start.
logs/	gateway.log, orchestrator.log, tui.log, web.log and, when used, telegram.log and heartbeat.log.
errors/	Error records that sharedcode doctor can work through.
pricing.json	Your own price overrides (optional), layered over a machine-written pricing_auto.json and the bundled table.
telegram/, whatsapp/	Channel configuration and state, once you set those up.

secrets.env is a key ring

sharedcode logs a warning when a secrets.env file can be read by group or other users. Keep it at mode 0600.

The global config

sharedcode configure --show prints the effective global config and the config of the selected agent. This is the start of what the quickstart produced:

{
  "upstream_endpoint": "http://127.0.0.1:8000/v1",
  "upstream_model": "qwen3.8-flash-next",
  "upstream_alias": "127.0.0.1",
  "backend": "vllm",
  "upstream_max_context": 256000,
  "models": [
    {
      "id": "qwen3.8-flash-next",
      "baseUrl": "http://127.0.0.1:8000/v1",
      "provider": "Local vLLM",
      "backend": "vllm",
      "default": true
    },
    {
      "alias": "nemotron-free",
      "baseUrl": "https://openrouter.ai/api/v1",
      "id": "nvidia/nemotron-3-super-120b-a12b:free",
      "backend": "unknown",
      "contextWindow": 1000000,
      "maxTokens": 0,
      "apiKeyEnv": "OPENROUTER_API_KEY",
      "headers": {
        "X-Title": "sharedcode"
      }
    }
  ],

The rest of the file enables the shipped skills one by one ("skills": {"moa": {"enabled": true}, ...}). Note upstream_max_context: configure asked the server for the model's context length rather than guessing it.

Model rows

models is the list the model picker offers. A row needs at least id (the model id the server expects) and baseUrl. The other fields:

Field	Meaning
alias	Short name for the row, usable wherever a model can be named.
default	true on the row new sessions use.
backend, provider	What kind of server it is (vllm, a hosted provider), used for display and routing.
apiKeyEnv	The name of the environment variable or secrets.env entry holding the key. Never put the key itself in config.json.
contextWindow, maxTokens	Context and output limits, when the server does not report them.
headers	Extra HTTP headers sent with each request.
api, auth, region	Used by the native Amazon Bedrock transport ("api": "bedrock-converse"), which needs the [bedrock] extra.

To add a hosted model, add a row whose apiKeyEnv names a variable, and put the key in ~/.sharedcode/secrets.env as NAME=value. Then run sharedcode gateway restart. The hosted row the default config carries is a working example. It does nothing until OPENROUTER_API_KEY exists, and you can delete it.

To try a different endpoint or model for a single run without touching the config, pass --endpoint and --model to sharedcode.

sharedcode configure

configure with no flags in a terminal runs the interactive setup. With flags it writes exactly what you give it:

Flag	Effect
--endpoint URL	The OpenAI-compatible base URL, for example http://127.0.0.1:8000/v1.
--model ID	The model id to pin. Required with --endpoint. sharedcode does not guess a model.
--system TEXT, --temperature N	The default system prompt and sampling temperature.
--enable-thinking / --no-enable-thinking	Whether to send enable_thinking to Qwen3-family chat templates.
--agent NAME	The agent that per-agent fields apply to (default jarvis).
--telegram-bot-token, --telegram-allowed-chat-ids, --telegram-allowed-user-ids, --telegram-mention-required	Telegram access for that agent. sharedcode telegram setup walks you through the same settings.
--show	Print the effective configuration and exit.

Agents and permission modes

The gateway hosts several agents. jarvis is the default you talk to, and it delegates to specialists. sharedcode agent list shows them, and sharedcode agent init creates a new one.

Each agent has a permission_mode, and every run can override it:

Mode	Flag	Behaviour
plan	--plan	Read-only; exhaustive answers, no changes.
ask	--ask	Asks before every mutation.
auto	--auto	Works autonomously and pauses before destructive actions. This is the default.

Environment variables

Most settings belong in config.json. These variables cover what does not, or what a service manager sets more naturally:

Variable	Effect
SHAREDCODE_HOME	The home directory (see above).
SHAREDCODE_AGENTS_HOME	The agents directory directly; its parent becomes the home.
SHAREDCODE_UPSTREAM_ENDPOINT, SHAREDCODE_UPSTREAM_MODEL	Used together, they configure a non-interactive first start (for example in a container), the same as configure --endpoint/--model.
SHAREDCODE_WEB_HOST, SHAREDCODE_WEB_PORT	The web UI's bind address and port (default 127.0.0.1:8110) for sharedcode web start and sharedcode-web.
SHAREDCODE_WEB_SECRET	The web session secret. Generated and stored in .env when unset.
SHAREDCODE_WEB_ADMINS	Comma-separated e-mail addresses that are always web admins.
SHAREDCODE_WEB_BASE_PATH, SHAREDCODE_WEB_TRUST_PROXY	Serve the web UI under a path prefix behind a reverse proxy; set the second to 1 so the UI trusts that proxy's forwarded headers.
SHAREDCODE_MAX_PROMPT_COST_USD, SHAREDCODE_MAX_GOAL_COST_USD	Spend caps per prompt (default 10) and per goal (default 25), in US dollars.
SHAREDCODE_MODEL_CATALOGUE_URL	Where model limits and prices are fetched from. Empty disables the fetch.
SHAREDCODE_PRICING_AUTOSYNC	Set to 0 to stop sharedcode writing pricing_auto.json.
SHAREDCODE_DISABLE_CRON	Turn off the scheduler that runs loops.
SHAREDCODE_DISABLE_EXTERNAL_DELEGATES	Set to 1 to block delegation to external agent CLIs.
SHAREDCODE_SKILLS_DIRS, SHAREDCODE_COMMANDS_DIRS	Extra directories (colon-separated) to search for skills and slash commands.
SHAREDCODE_VLLM_CONFIG	The router config for sharedcode-vllm (default vllm-router.yaml in the home directory).

Ports

Component	Address
orchestrator	http://127.0.0.1:8099
gateway	http://127.0.0.1:8100
web UI	http://127.0.0.1:8110

The gateway and orchestrator read their address from the gateway and orchestrator blocks of config.json. If you bind the gateway to a non-loopback address without an auth_token, it generates a temporary token rather than running open. sharedcode-serve only manages the default loopback layout: it refuses to start when the config points elsewhere, and it refuses any port that is already in use. Use sharedcode gateway start and sharedcode web start for other layouts.