Skip to content
adamkstinsonPublic

About

Rails for agent harnesses — one Ruby gem that builds, runs, and maintains agent directories.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

159 Commits

Folders and files

Repository files navigation

Remuda

Rails for agent harnesses. One Ruby gem that builds, runs, and maintains agent directories — the way Rails does for apps.

An agent is a directory. The harness lives in the gem, never copied into that directory. Pi is the only coding-agent runtime. Workflows are plain Ruby.

A remuda is the working string of saddle horses on a ranch: the pool you rope today's mount from, ride, and turn back. Many horses, one outfit. Many agents, one harness.

v1 is the CLI and workflow runner below. Internals live in design/.

Requirements

  • Ruby 3.2 or later (4.x is fine)
  • Bundler
  • Docker, only if you use sandboxed Pi (remuda with no subcommand, or Remuda.agent)

Install

From a clone of this repo:

git clone https://github.com/adamkstinson/remuda.git
cd remuda
bundle install
bundle exec remuda version    # this repo is the gem, not an agent

In an agent's .remuda/Gemfile (after remuda new, point at the git source or a path):

source "https://rubygems.org"

gem "remuda", git: "https://github.com/adamkstinson/remuda.git"
# gem "remuda", path: "../remuda"   # local checkout
bundle install

Inside an agent directory the command is remuda. Not bundle exec remuda. bundle exec is only for working on this gem from its own clone.

PATH on commands is an agent directory. Omit it when the current directory already is one (.remuda/Gemfile is present).

Scaffold an agent

remuda new ./ops
cd ops

Or scaffold the current directory: remuda new. Existing files are left alone, so running remuda new in an older agent adds only what it is missing, such as the remuda skill (.pi/skills/remuda/SKILL.md). That skill teaches the agent, in the sandbox or on the host, the CLI, how to write workflows, and the Ruby API on one page.

That writes identity and slots, not engine code:

ops/
├── AGENTS.md              identity
├── .mcp.json               MCP server URLs only (no secrets)
├── .env.example           copy to .env (gitignored); host-only
├── .pi/                   this agent's Pi config / skills
│   └── skills/remuda/     how to use Remuda: CLI, workflows, Ruby API
├── files/                 working files (agent memory)
└── .remuda/
    ├── Gemfile            harness pin (not the app Gemfile)
    ├── workflows/         plain Ruby scripts
    ├── channels.yml       channel bindings
    └── db/                remuda.sqlite3 created on first run/tick/console

There is no lib/ harness copy in the agent. Edit .remuda/Gemfile so remuda resolves (git or path), then bundle install with BUNDLE_GEMFILE=.remuda/Gemfile.

Run a workflow

A workflow is .remuda/workflows/<name>.rb — ordinary Ruby, no DSL.

# .remuda/workflows/hello.rb
puts "hello"
remuda run hello           # inside the agent
remuda run ./ops hello     # from elsewhere

That opens a workflow_runs row (trigger: "manual"), loads the script, then closes the row (ok or error). Inspect it in console (below).

Workflow APIs

Two library calls. They run on the host (your credentials). Recording is ambient when the Runner is in play.

Remuda.tool("server.method", **args)

Host-side MCP call. Split on the first dot: server plane, tool list_work_items. URL comes from .mcp.json; token from the agent's .env (PLANE_MCP_TOKEN or MCP_TOKEN). Raises on error.

{
  "mcpServers": {
    "plane": { "url": "https://mcp.example.com" }
  }
}
# .remuda/workflows/triage.rb
items = Remuda.tool("plane.list_work_items", project_id: "…", state_group: "backlog")
items.each { |item| warn item.inspect }

.mcp.json headers are sent on the call (${VAR} from the agent's .env). See the catalog while writing a workflow:

remuda tools                      # server.method names
remuda tools list_work_items      # description + schema
remuda tools ./ops plane.list_work_items

Remuda.agent(prompt)

One-shot sandboxed Pi in remuda-pi:latest unless the agent has .remuda/image (one line, the tag). Coding agents set that file to remuda-coding:latest. GH_TOKEN / GITHUB_TOKEN from the host .env is injected when present, with git configured (env only) to take https credentials from gh, so git push to an https GitHub remote works; .env is still not mounted. Result has output, ok, exit_code, and related fields. When pi exits non-zero, the agent step's error holds the exit code, pi's error message, the last 4 KB of its stderr and the last JSON event it printed, so a startup crash, a provider error and a cutoff can be told apart in remuda console. Values from .env and the agent's auth.json are replaced with [REDACTED] before anything is stored.

# .remuda/workflows/ping.rb
result = Remuda.agent("Reply with the single word pong.")
puts result.output

Model auth is per agent. The sandbox sets PI_CODING_AGENT_DIR to /agent/.pi/agent (the host agent’s .pi/agent/). That folder is this agent’s Pi user dir (auth.json, sessions, model catalog, settings.json). It does not pass --offline. The agent .env is never mounted. Host ~/.pi/agent is not used.

By default Remuda.agent does not pass --provider / --model. Pi uses defaultProvider / defaultModel from that settings.json (set in interactive remuda with /model, Ctrl+S). Remuda does not declare a second default. Override it for one call with provider: / model::

Remuda.agent(prompt)                                                # Pi's default
Remuda.agent(prompt, provider: "anthropic", model: "claude-sonnet-4-5")
Remuda.agent(prompt, model: "gpt-4.1")                              # Pi resolves the provider

Narrowing the tools for one call

By default the sandbox sees the whole catalog: every Pi built-in, every server in .mcp.json, and the channels tools when a transport is bound. Narrow that for a single call with tools: (allowlist) or exclude_tools: (denylist). The two are mutually exclusive. An empty allowlist passes --no-tools.

Remuda.agent(prompt, tools: %w[read grep channels_send_message])   # allowlist
Remuda.agent(prompt, exclude_tools: %w[bash write edit])           # denylist
Remuda.agent(prompt, tools: [])                                    # no tools

Tool names are Pi's: built-ins (read, bash, edit, write, …) and <server>_<tool> for MCP (channels_send_message, planet_list_work_items).

The Hash form of tools: also pins arguments. A pinned argument is filled in by the host, removed from the tool's advertised schema, and refused if the model sends a different value. Pins are only valid for tools Remuda answers on the host — today the channels server. Pinning a forwarded MCP server (Planet, Twenty, …) raises before the container starts.

# The agent may read, but it can only reply in the thread this run came from.
Remuda.agent(prompt, tools: {
  "read" => true,
  "channels_send_message" => { jid: msg.jid, thread_id: msg.thread_id },
  "channels_read_thread"  => { jid: msg.jid, thread_id: msg.thread_id }
})

The agent step's input records tools / exclude_tools as given, pins included.

The override is recorded on the agent step's input. .env PI_PROVIDER / PI_MODEL are not a fallback for it.

session_id: resumes an existing Pi session, creating it if it is missing (pi --session-id). Pass the session_id a previous run returned to continue that conversation with its prior turns in context. Session files live under .pi/agent/sessions/, so they survive restarts. The step's session_id column records what Pi reports, which for a resumed run is the id you passed.

first = Remuda.agent("Start the incident log for INC-42.")
Remuda.agent("Add the on-call rotation to it.", session_id: first.session_id)

Put credentials in <agent>/.pi/agent/auth.json (login inside remuda), or put the provider's API key in the agent .env. Before every run, remuda run and bare remuda write the .env keys into that auth.json on the host, replacing the providers .env names and keeping every other entry, so a rotated key takes effect on the next run. PI_PROVIDER limits which key is written; it does not pick the model.

# in the agent's .env (gitignored) — auth shortcut only
PI_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...

Do not put third-party SaaS tokens in .env. Self-hosted MCP tokens may live there; the file is never mounted into the sandbox.

The images ship a built-in darkhorse provider for ai.darkhorse.so (Dark Horse's OpenAI-compatible inference API). One line in the agent's .env

DARKHORSE_API_KEY=dh_...

gives every model that key can reach — the provider lists the live catalog from GET /api/v1/models, so there is no models.json to maintain and nothing goes stale when the catalog changes. Then defaultProvider: "darkhorse" in .pi/agent/settings.json, or provider: "darkhorse", model: "glm-5.2" on a Remuda.agent call, works like any other provider. Without the key the provider lists no models and Pi starts exactly as it would without it.

MCP from inside the sandbox

The images ship Remuda's Pi profile: the pi on PATH loads an MCP client (pi-mcp-adapter, pinned in image/Dockerfile) and the darkhorse provider extension, and points the adapter at this run's copy of .mcp.json and nothing else. The profile also passes --no-mcp, so Pi's own built-in MCP support — which the adapter replaces — does not start and does not warn about losing the /mcp command to it. A project's own .pi/extensions/ still load normally. An agent with no MCP servers gets the image's empty config, never its own .mcp.json; that explicit config is also what stops the adapter writing "-builtin:mcp" into the agent's tracked .pi/agent/settings.json. A directory declares its servers in its root .mcp.json: pi's own project config, so pi on the host, Remuda.tool, and the box all read the same file. Header values use pi's ${VAR} syntax; the value lives in .env. Client options sit next to the URL:

{
  "settings": { "toolPrefix": "server" },
  "mcpServers": {
    "plane": {
      "url": "https://plane.example.com/mcp",
      "headers": { "X-Plane-Key": "${PLANE_API_KEY}" },
      "directTools": true
    }
  }
}

With directTools: true Pi sees plane_list_projects and the rest as its own tools. Without it Pi reaches them through one mcp proxy tool.

The sandbox reaches MCP servers that declare headers through a per-run forwarder on the host. .mcp.json stays the declaration and is not changed on disk. For each run Remuda writes a copy and mounts it read-only over the agent's own .mcp.json (/agent/.mcp.json), so the box and pi read one file; an agent with no .mcp.json gets the copy at /run/remuda/mcp.json, beside the prompt, instead. REMUDA_MCP_CONFIG names whichever was mounted:

  • a server with headers points at http://host.docker.internal:<port>/<run token>/<server> and carries no headers. The forwarder fills the declared headers (${VAR} from the agent .env, then the process environment, the same rule as Remuda.tool) and passes the request, streaming, to the real URL.
  • a server with no headers keeps its URL; the agent calls it directly.
  • a declared variable with no value is not sent blank. The forwarder answers that server with 401 and names the missing variable.

A variable the workflow sets on the process before Remuda.agent reaches the forwarder the same way. The forwarder starts with the container and stops when it exits, for Remuda.agent and for interactive remuda. It listens on the Docker bridge address, and every path starts with a random token only that run's .mcp.json holds. .env is still never mounted. On a host with a firewall (ufw), allow the bridge in (ufw allow in on docker0) or the box cannot reach the forwarder.

OAuth MCP servers

A server that signs in with OAuth (Gmail, Calendar) is declared in .mcp.json the way pi-mcp-adapter declares it, and handled on the host like a ${VAR} header:

"gmail": {
  "url": "https://gmailmcp.googleapis.com/mcp/v1",
  "auth": "oauth",
  "oauth": {
    "clientId": "1234.apps.googleusercontent.com",
    "clientSecret": "${GOOGLE_OAUTH_CLIENT_SECRET}",
    "scope": "https://www.googleapis.com/auth/gmail.readonly",
    "authorizationParams": { "access_type": "offline", "prompt": "consent" }
  }
}

The tokens live in pi-mcp-adapter's encrypted-file store, .pi/agent/mcp-oauth-encrypted/ (gitignored), encrypted with PI_MCP_ADAPTER_OAUTH_FILE_KEY from .env. Set "oauthCredentialStore": "encrypted-file" in .pi/agent/settings.json (new agents have it). Connect once with the adapter, on the host, as this agent:

node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"  # key, once, into .env
env $(grep -E '^(PI_MCP_ADAPTER_OAUTH_FILE_KEY|GOOGLE_OAUTH_CLIENT_SECRET)=' .env | xargs) \
  PI_CODING_AGENT_DIR=$PWD/.pi/agent pi -e ~/.pi/agent/npm/node_modules/pi-mcp-adapter
# then, in pi:  /mcp-auth gmail

After that Remuda.tool, Remuda.agent, channel replies, and interactive remuda all reach the server. Remuda reads the store, refreshes the access token when it is within five minutes of expiry (writing it back in the adapter's format), and sends Authorization: Bearer. The box's copy of the server points at the forwarder with "auth": false; the key and the token never enter the container. A server with no key, or not connected, gets a 401 that names the fix.

Channels

How a person reaches an agent, and how the agent answers. Transports live in the gem, bindings in the agent's .remuda/channels.yml, tokens in its .env. Mattermost is the transport today.

# .remuda/channels.yml
transports:
  mattermost:
    url: https://chat.example.com
    token_env: MATTERMOST_TOKEN   # the bot's personal access token, in .env
    # mentions_only: true         # DMs and posts that tag @bot (threads too)
    # ignore_bots: true           # never answer another bot
    # allow: [adam]               # only these usernames reach the agent

Remuda.channels builds the registry from that file. An agent with no bindings gets an empty registry, and every call on it is a no-op.

channels = Remuda.channels
channels.on_message do |msg|
  listed = msg.files.filter_map do |file|
    next unless file.path
    dest = File.join("files", file.name)
    FileUtils.mkdir_p("files")
    FileUtils.cp(file.path, dest)
    dest
  end
  prompt = msg.text.to_s
  prompt += "\n\nAttached files:\n" + listed.map { |p| "- #{p}" }.join("\n") if listed.any?
  result = Remuda.agent("Reply to #{msg.sender_name}: #{prompt}", session_id: channels.session_for(msg))
  outbound = Dir.glob("files/outbound/*")
  channels.send_message(jid: msg.jid, text: result.output, thread_id: msg.thread_id, files: outbound)
end
channels.start_all
sleep

Passing session_id: channels.session_for(msg) makes every message in a thread one growing Pi session, so a follow-up like "yes, do that" resumes with the conversation so far. The mapping is the channel_threads table: one row per (jid, thread_id), minted (a UUID) on first sight and touched on every message. A DM is a thread too, and a top-level mention that starts a new thread starts a new session.

When a workflow posts a new thread, bind it to the session that wrote it so later replies resume that session:

result = Remuda.agent("Write the morning brief for the ops channel.")
thread = Remuda.tool("channels.send_message", jid: ops_jid, text: result.output)["thread_id"]
Remuda.channels.bind_thread(jid: ops_jid, thread_id: thread, session_id: result.session_id)

bind_thread upserts, so an explicit binding overwrites an earlier one. Nothing is bound automatically: the run that posts the root only knows its own session_id after it returns.

A message carries jid (where to reply: mattermost:<channel_id>), thread_id (the root post; reply with it to stay in the thread), sender_name, text, and files (attachments already downloaded to disk). send_message(..., files: ["photo.jpg"]) uploads those paths. Inbound arrives over the Mattermost websocket and goes to on_message on one worker thread, in order, so a long agent run does not stall the socket. While that handler runs, the bot shows as typing in the channel and the thread. The adapter reconnects with backoff. After a reconnect it backfills posts it missed, so a dropped connection does not drop a message.

Outbound-only (a workflow posting a digest):

mm = Remuda.channels[:mattermost]
mm.send_message(jid: mm.dm_jid("adam"), text: "Nightly run finished.")
mm.send_message(jid: mm.channel_jid(team: "team", channel: "ops"), text: "…")

Microsoft Teams

Teams works the other way around from Mattermost. Microsoft's Bot Connector POSTs every message to an HTTPS endpoint you host, and the bot replies over REST. No SDK; the transport is Remuda::Channels::Teams.

# .remuda/channels.yml
transports:
  teams:
    app_id_env: TEAMS_APP_ID          # defaults shown; the values live in .env
    app_secret_env: TEAMS_APP_SECRET
    tenant_id_env: TEAMS_TENANT_ID
    # mentions_only: true             # personal chats, and posts that @mention the bot
    # allow: [<entra object id>]      # only these senders reach the agent

The channel is a Rack app: it responds to call(env). Serve it from a host app (mount Remuda.channels(dir)[:teams], at: "/api/messages") or with any Rack server. TLS in front of it (Caddy, …) is yours:

# config.ru in the agent directory
require "remuda"
teams = Remuda.channels(__dir__)[:teams]
teams.on_message do |msg|
  result = Remuda.agent("Reply to #{msg.sender_name}: #{msg.text}", session_id: teams.session_for(msg))
  teams.send_message(jid: msg.jid, text: result.output, thread_id: msg.thread_id)
end
teams.start!
run teams

Every POST must carry a Bot Framework JWT: an RS256 token signed by a key from Microsoft's OpenID metadata, issued by https://api.botframework.com, with your app id as audience and a serviceUrl claim that matches the activity. Anything else gets 401. A replayed activity id is dropped. The POST is answered 200 at once, and on_message runs on one worker thread.

jid is teams:<conversation id>, thread_id is the root message of a channel thread (or the activity id in a chat), and sender_name is the display name. allow: matches Entra object ids, not names. To message someone first (a digest, "shipment ready for review"), the bot needs a conversation reference from an earlier message in that conversation. References are stored in the agent's SQLite (channel_sessions), so send_message(jid:, text:) still works after a restart. Text and Markdown only: no Adaptive Cards and no files in v1.

One-time setup:

  1. Microsoft Entra ID: a single-tenant app registration. Note the application (client) id and tenant id, and create a client secret.
  2. An Azure Bot resource on that app id. Enable the Microsoft Teams channel and set the messaging endpoint to https://<your host>/api/messages.
  3. A Teams app package (manifest plus two icons) with bots[].botId = the app id and scope personal (plus team / groupChat if wanted). Upload it for pilot users or publish it to the org catalog. The tenant's Teams admin must allow custom apps.

Put the three values in the agent's .env as TEAMS_APP_ID, TEAMS_APP_SECRET, TEAMS_TENANT_ID.

Channels as a tool

When channels.yml binds at least one transport, three tools appear alongside the MCP ones: channels.list_channels, channels.send_message, and channels.read_thread. remuda tools lists them, and with no bindings they are not there.

list_channels is everywhere the agent can post, as one flat list across all its transports — several Mattermost channels, a Teams conversation, whatever is bound — each with the jid that send_message takes. Nothing has to hard-code a channel id; the agent can look and choose.

Remuda.tool("channels.list_channels")
# => { "channels" => [
#      { "jid" => "mattermost:abc", "name" => "dark-horse/ops", "transport" => "mattermost", "kind" => "channel" },
#      { "jid" => "mattermost:def", "name" => "@adam",           "transport" => "mattermost", "kind" => "dm" },
#      { "jid" => "teams:…",        "name" => "General",         "transport" => "teams",      "kind" => "channel" } ] }

kind is channel, private, dm, or group. Mattermost lists every membership on every team the bot is on. Teams has no directory a bot can browse, so it lists the conversations it has already heard from.

read_thread reads one thread, so an agent that was tagged into a conversation it has never seen can catch up without the whole thread being prepended to every prompt. It returns the root, the newest posts oldest-first, how many older posts were left out, and a cursor for the next page:

Remuda.tool("channels.read_thread", jid: "mattermost:abc", thread_id: "rootid")
# => { "root"  => { "id" => "rootid", "sender_name" => "adam", "text" => "topic", … },
#      "posts" => [ { "id" => "p2", "sender_name" => "adam", "text" => "…",
#                     "created_at" => "2026-01-01T00:00:00Z", "from_bot" => false,
#                     "files" => ["cat.jpg"] }, … ],
#      "omitted" => 179, "before" => "p1" }
Remuda.tool("channels.read_thread", jid: "mattermost:abc", thread_id: "rootid", before: "p1")

limit is 1-50 (default 20). before is the before from a previous call; keep passing it until it comes back nil to walk the whole thread. Posts from bots (including this bot) are marked from_bot so the agent does not answer them or quote them back. Files are listed by name only, never downloaded. The host bounds each call: posts are truncated at 4,000 characters and a call returns at most ~16,000 characters in total, dropping the oldest and bumping omitted. read_thread raises when no channel delivers, the same as send_message.

From a workflow script both go through Remuda.tool and are recorded as workflow_steps rows (kind: "tool", name: "channels.send_message" / "channels.list_channels" / "channels.read_thread"). send_message raises when no channel delivers:

Remuda.tool("channels.send_message", jid: "mattermost:abc", text: "Digest ready.",
                                     thread_id: nil, files: ["files/digest.pdf"])
# => { "thread_id" => "…" }

Inside the sandbox Pi sees them as channels_list_channels, channels_send_message, and channels_read_thread. The runner adds a channels server to the box's .mcp.json that points at the per-run forwarder, and the forwarder answers it on the host with the agent's bound channels. MATTERMOST_TOKEN never enters the container. Each send and read is a step on the run that started the box. The agent attaches files by their in-box path (/agent/files/report.pdf). Paths outside the agent directory, .env, and .remuda/ are refused. To scope a run to the thread it was tagged in, pin jid and thread_id on both channel tools — the agent can then read the thread it came from and reply there, and nowhere else:

# A Hash tools: is an allowlist; list every built-in and MCP tool the agent
# keeps, and pin the channel tools to this thread.
Remuda.agent(<<~PROMPT, tools: {
  You were tagged in a thread. If you need what came before, call
  channels_read_thread. Posts marked from_bot are other agents; do not
  repeat their text. When you are done, reply with channels_send_message.
PROMPT
  "read" => true, "grep" => true, "bash" => true, "write" => true, "edit" => true,
  "channels_read_thread"  => { jid: msg.jid, thread_id: msg.thread_id },
  "channels_send_message" => { jid: msg.jid, thread_id: msg.thread_id }
})

A server named channels in .mcp.json takes precedence over the built-in one.

Not shipped yet: a remuda command that supervises channels, and durable channel state (the cursor is in memory; pass since: to resume). See design/06-channels.md.

Console

IRB on this agent's SQLite — not Pi.

remuda console
remuda console ./ops

Top-level constants: WorkflowRun, WorkflowStep, Schedule.

WorkflowRun.last
WorkflowRun.where(status: "error").order(id: :desc).limit(5)
WorkflowStep.where(workflow_run_id: 1).order(:position)

Remuda.tool / Remuda.agent work here too. They do not write steps unless a run is in progress (Current.run).

Schedule a workflow

remuda schedule hello --cron "0 7 * * *"
remuda schedule ./ops hello --cron "10 */6 * * *" --timezone America/Los_Angeles
remuda schedules
remuda unschedule hello

That inserts (or replaces) a schedules row in the agent's SQLite. One row per workflow name. --timezone defaults to UTC. The command prints the row and a copy-pasteable crontab line that runs Remuda tick (not .agentworks/bin/tick):

* * * * * cd /path/to/ops && remuda tick >> /path/to/ops/.remuda/tick.log 2>&1

No daemon. Install that one line on the host crontab. Tick finds unpaused rows with next_occurrence <= now, advances last_occurrence / next_occurrence first, then fires the workflow through the same Runner (trigger: "schedule"). A run that outlasts the minute is not seen as due again by the next tick, and when two ticks race for one occurrence only one wins it. If that workflow still has a running row, the new run is skipped.

remuda tick           # inside the agent
remuda tick ./ops

Images

Build the sandbox images from image/ when the Dockerfiles change. They are not rebuilt when the gem bumps:

docker build -t remuda-pi:latest image/
docker build -t remuda-coding:latest -f image/Dockerfile.coding image/
ruby -Ilib test/integration/mcp_client.rb   # Pi in the image can call MCP

Interactive Pi (sandboxed)

From inside an agent directory, no subcommand:

remuda

That is docker run --rm -it of the image in .remuda/image (default remuda-pi:latest). Same sandbox Remuda.agent uses. The directory you ran from is mounted at /agent read-write, except .env (masked, empty in the box) and .remuda/ (masked, apart from .remuda/workflows/). Workflows are writable here and read-only for Remuda.agent.

Extra mounts

An agent directory holds the agent — skills, workflows, config. What it works on lives elsewhere and is mounted in. Declare it in .remuda/mounts.yml:

core: ../../Products/core        # read-write (default)
docs: ../../Docs:ro              # read-only
index.yml: ../../index.yml:ro    # a single file

Each entry is bound at /work/<name>, for both remuda and Remuda.agent. Paths are relative to the agent directory. A path missing on the host is an error rather than a root-owned directory Docker made for you. /agent is still the agent's own directory; a git commit in /work/core lands in that repo, not the agent's.

The sandbox adds host.docker.internal → host gateway. Set REMUDA_EXTRA_HOSTS=hostname:ip[,...] for more. .mcp.json may list both a local url and a tailscale_url. When REMUDA_LOCAL_HOSTNAME matches this machine, Remuda uses url; otherwise tailscale_url. Host-side Remuda.tool rewrites host.docker.internal to 127.0.0.1.

Model auth is per agent, same as Remuda.agent. The sandbox sets PI_CODING_AGENT_DIR to /agent/.pi/agent (the host agent’s .pi/agent/). It does not copy host ~/.pi/agent/auth.json. A login inside the box writes to the agent’s .pi/agent/ on the host and survives the container.

CLI (v1)

Command What
remuda new [PATH] Scaffold an agent directory
remuda run [PATH] WORKFLOW Run .remuda/workflows/WORKFLOW.rb once, recorded
remuda tick [PATH] Fire due schedules through the same Runner
remuda schedule [PATH] WORKFLOW --cron EXPR Insert/replace a schedules row; print crontab line
remuda unschedule [PATH] WORKFLOW Delete that workflow's schedules row
remuda schedules [PATH] List schedules and the crontab line
remuda tools [PATH] [NAME] List MCP tool names from .mcp.json, or print one tool
remuda console [PATH] IRB on this agent's SQLite
remuda Sandboxed Pi (must already be in an agent directory)
remuda version Gem version
remuda help Subcommands (console and bare remuda are omitted from help)

Not shipped: a channels command (the library is above). There is no remuda generate — add workflow scripts and skills as ordinary files.

Boundaries

  • Not a SaaS. Your machine, your directories.
  • Not an agent framework. Behavior is the directory's files.
  • Not multi-tenant. Many directories, one gem.

Lineage

Successor to Agentworks. That project proved the engine and then stenciled it into every agent. Remuda keeps the ideas, not the stencil, and is not backwards compatible. Live Ops/Assistant agents stay on Agentworks until migrated.

License

MIT. See LICENSE.

About

Rails for agent harnesses — one Ruby gem that builds, runs, and maintains agent directories.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages