Core concepts

An OpenRoutines agent is a git repository that does a job. This is how the pieces fit together.

One agent, one job

The repository is the agent: its config, its routines, the skills they use, and its encrypted credentials. Every run starts with the agent’s name from openroutines.yml; optional instructions add standing context shared by every routine. You build, review, and ship it like the rest of your software.

That job is bigger than any single piece of work. An agent that keeps an accurate picture of what customers need and what the team shipped might check documentation on Mondays, sort feedback on Thursdays, and draft release notes when a release lands. Work that needs a different mandate belongs to a different agent.

Routines do the work

A routine is a markdown file in routines/. The frontmatter declares when it runs and what it may touch, and the body is the prompt. That’s the whole unit of work.

Routines don’t call each other, and there’s no orchestration graph to maintain. Each one is a standing instruction the agent carries out on its own schedule. Adding to what your agent does means adding a file. See Creating routines.

Runs are sandboxed

A routine gets what its frontmatter declares and nothing else: these skills, these credentials, these tools, this model. Web access is off unless asked for. The agent’s entire reach is greppable in its own source, so a new capability arrives as a diff you can review.

The run itself is a fresh model process in a container, held to a workspace built from those grants. It can’t reach the credential store, the deploy key, or anything another routine is doing, and it carries nothing from the last time its own routine ran.

Knowledge is the shared record

Anything that has to outlive a run gets written down. Four kinds of record cover it: events for what happened, tasks for what someone must do, context for what’s worth keeping, and a private ledger per routine for its own working state.

This is also the only connective tissue between routines. One that spots a documentation gap files a task; the routine that writes documentation picks it up on its next run. Neither knows the other exists.

Knowledge lives on its own git branch, pulled before each run and pushed after, so it survives redeploys and rollbacks while staying versioned and reviewable. See Knowledge.

Teamwork takes care of itself

Most of what makes a good teammate is communication: they say what they’re planning, what they did, where they’re stuck, and what’s still on their list. Teamwork primitives give your agent the same habits, built on the knowledge it already keeps: declaring intentions, reporting progress, calling out blockers, and tracking tasks.

You focus on the routines that do the work. They write down plain facts as they go, and reporting routines read those facts later to compose updates for the team. So you can write working routines without thinking about reporting at all, then point any number of reports and destinations at the facts they leave behind. See Teamwork.

The supervisor runs the agent

Start the container and one process comes up inside it: the supervisor, a small binary that is the whole runtime. Every minute it re-reads your routines’ frontmatter and starts whatever is due, so the files are the schedule and there’s nothing to register.

It handles everything around a run, too. It pulls the latest knowledge before one starts and pushes what the run recorded after, retries an attempt that failed, and files a task for a person when it has to give up. That’s what makes an unattended agent survivable: a fire missed while the container was down runs late instead of never, a routine never runs on top of itself, and one that keeps failing cools down instead of retrying forever.

Locally the supervisor reads your working tree, so an edit lands on the next tick. Deployed, it reads the copy of the repository baked into its image, so changes reach production when you redeploy, and knowledge is the only thing that travels the other way. See Deploying your agent.