Skip to content

sharedcode

sharedcode is an agent runtime you run on your own machine, pointed at inference you control. You install it with pip, point it at an OpenAI-compatible endpoint such as a vLLM server on your own GPU, and work with agents from a terminal UI, a browser, Telegram or WhatsApp. Sessions, memory and configuration stay in one directory on your disk.

It exists because the alternative has become a bad deal. The current model asks you to pour product direction, customer knowledge and half-formed ideas into systems you do not control. In return you get rising prices, quotas that move, quality that sags under load, and products that are blocked when a vendor changes its mind. sharedcode takes the other side: the intelligence layer of a company is too important to rent blindly. If your AI stack is not sovereign, your cognition stack is not sovereign.

What it is

  • A terminal UI and one-shot CLI. Run sharedcode for the TUI, or sharedcode -p "..." to ask one question and get the answer on stdout.
  • A local gateway and orchestrator. Two small daemons on 127.0.0.1. The gateway acknowledges input fast and streams events. The orchestrator owns the turn loop, tools and engines. Every client talks to the same pair and the same session store.
  • A browser UI (the [web] extra) with sessions, usage, agent monitoring, tasks, loops, goals, voice and an agent builder.
  • Channels: a Telegram bot, a WhatsApp self-chat ([whatsapp]) and a realtime voice server ([realtime]).
  • Model plumbing: any OpenAI-compatible endpoint, native Amazon Bedrock Converse ([bedrock]), an optional local vLLM replica router ([vllm-router]), and per-call cost and speed telemetry that is stored locally.
  • Agents and tools: several built-in agent profiles, an MCP client with bundled memory, web and delegation servers, a skill system with shipped skills, durable scheduled loops and goals. It can also drive installed coding-agent CLIs, for example Claude Code, Codex, Cursor or Antigravity, as engines.
  • Your data in plain files: one append-only <session_id>.jsonl per session plus a rebuildable SQLite cache, under ~/.sharedcode/.

What it is not

  • Not a hosted service. There is no account to create and no server of ours in the loop. If you never configure a hosted provider, your prompts only go to the endpoint you configured.
  • Not a model. sharedcode ships no weights. It needs an endpoint: a vLLM or similar server you run, a private workstation, or a hosted API if you choose one. The default configuration also contains one hosted row, a free model on OpenRouter. It only works if OPENROUTER_API_KEY is set, and you can delete it from config.json.
  • Not a process supervisor. sharedcode-serve starts the stack and reports a component that dies; it never restarts it. If you want restarts, install the systemd user units (see Operations) or use your own supervisor.
  • Not hardened for the open internet by default. Every listener binds to loopback. Putting the web UI behind a public address is a deliberate step you take with your own reverse proxy and TLS.
  • Not stable yet. This is the first public release (0.1.0, marked Beta). The feature set is complete and tested, but the configuration format and the Python API can still change. See Project status.

Where to start

  1. Install the base package, plus any extras you need.
  2. Follow the Quickstart. Every command on that page was run for this documentation, and the output shown is what came back.
  3. Read Configuration to see what lives in ~/.sharedcode/.
  4. Components maps the twenty-one Python packages, and Operations covers running it day to day.

On outbound traffic

"No telemetry" is easy to claim and hard to check, so here is what the code actually contacts. There is no usage-reporting endpoint. The hosts in the source are model providers you configure, the services behind external agent CLIs you choose to install, Telegram and WhatsApp when you enable those channels, YouTube for the optional transcript tool, and public model catalogues. By default the model catalogue (output limits and prices) is fetched from models.dev and refreshed once the local copy is a day old. On an air-gapped host, set SHAREDCODE_MODEL_CATALOGUE_URL to an empty value to switch it off.