Getting started

Go from nothing to an agent running in production: install the CLI, scaffold one, write its first routine, and deploy it.

Prerequisites

  • git — the agent is a repository, so you commit, push, and deploy like any other project. As it works, the agent writes what it learns back to a branch of its own.
  • Docker — routines run in a container, locally and in production. Only running one needs Docker, so you can scaffold and configure an agent without it.
  • An API key for at least one model provider (Anthropic, OpenAI, and so on) — configure encrypts it into the agent for you.

That’s the whole list. Everything else the agent needs, opencode included, ships inside the container.

Install the CLI

curl -fsSL https://get.openroutines.dev/install.sh | bash
openroutines --version

The binary lands in ~/.local/bin. Set OPENROUTINES_INSTALL_DIR to put it somewhere else, or OPENROUTINES_VERSION to pin a version.

Scaffold and configure

openroutines new my-agent
cd my-agent
openroutines configure

new creates a fresh git repository with the agent’s skeleton:

  • openroutines.yml — the agent’s name, timezone, and defaults, plus an optional owner and standing instructions.
  • routines/ — the work the agent does, one markdown file per job, with the schedule at the top and the prompt below. A working one comes with it.
  • skills/ — procedures a routine can call on when it needs them, in the open Agent Skills format. Empty to start.
  • AGENTS.md — instructions for the coding agent you build with, so it starts out knowing how the repo fits together.
  • avatar.svg and avatar.png — a generated avatar for the agent.
  • master.key — the key that encrypts the agent’s credentials, kept out of the repository.
  • a Dockerfile, an opencode.json permission policy, and a pinned framework version — how the container is built, which tools a run may use, and which release of OpenRoutines you’re on.

A knowledge/ directory joins them on the first run. That’s what the agent records as it works.

configure fills in openroutines.yml and tells you what’s still missing. Run it anytime. The agent’s name becomes standing context for every run. If every routine should share more context, add optional instructions to openroutines.yml; routine-specific work still belongs in routine files.

Back up master.key somewhere safe: without it the agent’s credentials can’t be decrypted, and production needs a copy of its own.

Pick your models

configure asks for a default model and writes it to openroutines.yml. A model string is provider/model, like anthropic/claude-sonnet-5. Both halves come from models.dev, the catalog opencode reads: search for a model there and you get its id, along with what it costs and how much context it holds.

Any routine can pick a different model in its frontmatter (see Creating routines), and you can point the agent at your own endpoint instead (see Models).

Your first routine

openroutines routines new doc-drift

Edit the generated file: schedule and scope in the frontmatter, the prompt in the body. Then rehearse it.

openroutines routines run doc-drift --rehearse

A rehearsal is the real routine against the real world, told to look and not touch, and nothing it does is kept. Repeat it as often as you like while you work on the prompt. You can also hand a routine a scenario you wrote instead of the live world, which is how you compare models or replay a slow week (see Rehearsals).

When the prompt does what you want, run it for real:

openroutines routines run doc-drift

That’s a live run, in the same container production uses and with the routine’s own credentials and tools, so it can send the email or open the pull request for real. What it learns is discarded unless you add --write-knowledge.

Deploy it

The agent ships as a plain Docker container, so anything that runs one runs your agent: a VPS, Fly, Render, your homelab. There’s nothing else to provision.

It needs a git repository to push to, since that’s where its knowledge lives, and two secrets at boot: the master key that decrypts its credentials, and a deploy key scoped to the repository that lets it push what it learns. You hand both to the container as environment values or mounted files.

One container is the whole agent, with nothing to scale out. It runs the copy of the repo baked into the image, so changes you push reach production on your next deploy.

openroutines check validates all of this before you ship, so put it in CI. Deploying your agent has the commands.

From here the agent runs itself. The supervisor fires each routine on schedule and the agent reports its own work, so you read what it did rather than go asking.