Skip to content
tomo

Quick start

From an empty terminal to a working agent: set a key, onboard, talk to tomo in the terminal, then open the local web chat.

This walks the first run end to end. By the last step you have an agent you can talk to from the terminal and from a browser, all on your own machine.

1. Set a provider key

The starter config points at Anthropic and reads the key from your environment, so export it first:

export ANTHROPIC_API_KEY=sk-ant-...

Pointing at a local or self-hosted model instead? Set that provider's base_url in the config after the next step, and export whatever key it expects (or none).

2. Onboard

tomo onboard sets up ~/.tomo and writes a starter config.yaml. It creates the memory and skills directories beside it, and it will not overwrite a config you already have.

tomo onboard

wrote /home/you/.tomo/config.yaml

next:
  1. export ANTHROPIC_API_KEY=... (or point a provider at a local server)
  2. tomo chat

Open ~/.tomo/config.yaml if you want to change the default model, adjust the policy, or wire up a channel. The defaults are ready to go as they are.

3. Talk to it in the terminal

tomo chat is a streaming REPL against the configured model:

tomo chat

tomo · anthropic/claude-fable-5 · /new starts over, /exit leaves

you> what can you do on this machine?
tomo> I can read and fetch things freely, and I can write files or run
commands with your approval each time. Want me to show you the current
policy?

you>

Two REPL commands: /new clears the working context and starts over, and /exit leaves.

By default the conversation is not saved. Pass -s (or --session) with a name to persist it in the ledger and pick up where you left off next time:

tomo chat -s daily

You can also override the model for a single run with -m (or --model), for example tomo chat -m anthropic/claude-fable-5.

4. Open the web chat

tomo serve runs tomo as a daemon. The web chat is always on, bound to loopback by default, and any channels you configured start alongside it:

tomo serve

tomo serving on http://127.0.0.1:8765
  channel: web

Open http://127.0.0.1:8765 in a browser and you have the same agent in a chat window. It listens only on your machine unless you change --addr.

Where to go next

  • Connect a chat app: the channels guide wires up Telegram, Discord, Slack, and iMessage, each with an allow-list.
  • Understand the gate before you loosen it: the policy and safety guide is the whole trust model, what runs, what asks, and what taint does.
  • Browse the rest of the guides for memory and skills, workers, scheduling, voice, and MCP.
3 min read