AgentOS markAgentOS

Operations


This guide covers day-two commands: sessions, cron, cost, diagnostics, replay, migration, durable agents, MCP, and install inventory. Use it after the first successful chat or gateway run. To operate a gateway on another machine, see Remote Access.

Sessions

Sessions are durable chat/task histories. Use them to resume, inspect, export, or clean up prior work.

agentos sessions list
agentos sessions show <session-key>
agentos sessions resume <session-key>
agentos sessions export <session-key>
agentos sessions abort <session-key>
agentos sessions delete <session-key>

Use session export when exact old context matters or when you want to debug a long-running task outside the chat UI.

For resume, abort, export, and cleanup workflows, see Sessions and History.

Durable Agents

AgentOS supports durable agent entries, including the built-in main agent.

agentos agents list
agentos agents add research --name Research --workspace /path/to/research
agentos agents delete research

Use durable agents when you want separate workspaces, instructions, or tool profiles for recurring roles. Restart the gateway after agent config changes.

Keep each durable agent's instructions focused on that role instead of turning every agent into a copy of main.

For agent examples and concepts, see Durable Agents.

Cron and Scheduled Runs

Cron jobs run AgentOS tasks on a schedule.

Inspect jobs:

agentos cron list
agentos cron status <job-id>
agentos cron runs <job-id>

Add a simple recurring reminder:

agentos cron add \
  --every 1h \
  --text "Check for urgent project updates and summarize them" \
  --name hourly-project-check

Add a daily cron-style task:

agentos cron add \
  --cron "0 9 * * 1-5" \
  --tz "America/Los_Angeles" \
  --text "Prepare my weekday morning briefing" \
  --name weekday-briefing

Manage jobs:

agentos cron update <job-id> --enabled
agentos cron remove <job-id>
agentos cron run <job-id>

Good uses:

  • morning briefings;
  • recurring research digests;
  • PR or CI checks;
  • channel-delivered reminders;
  • scheduled memory consolidation or reporting tasks.

Pair cron with channels when the output should be delivered somewhere other than the local Web UI.

For scheduling examples, delivery options, and troubleshooting, see Scheduling.

Cost and Usage

Inspect usage and estimated cost:

agentos cost
agentos cost --by-model
agentos cost --json

Use cost inspection after tool-heavy, routed, or long-context tasks to understand actual runtime behavior.

For cost investigation workflow, see Usage and Cost.

Always-On Gateway

For a gateway that should keep running unattended (a home server, a laptop that sleeps), install it as a user service and let it watch itself:

agentos gateway install --port 18791
agentos gateway status --deep --json
curl -s http://127.0.0.1:18791/ready
agentos channels status --json
  • Restarts. launchd (macOS) or systemd (Linux) restarts the gateway when it dies; a configuration error (exit 78) is not restarted into a loop by systemd. See Run as a service.
  • Crash loops. Three unclean boots in five minutes start the gateway in safe mode: channels, cron and heartbeat are held back, /ready reports state: "safe_mode", and agentos doctor names the way out. Fix the cause, then agentos channels start --yes, or let it clear by itself after five quiet minutes.
  • Sleep. After the machine wakes, the gateway restarts idle channels (gateway.thaw in the log; a restart that fails while the network comes back is retried with backoff) and runs each overdue cron job once. A 5-minute health sweep restarts channels that are disconnected, stuck, start_failed or stale-socket; one stopped on bad credentials (terminal) waits for you — doctor shows the fix.
  • Missed jobs. Agent jobs missed while the gateway was down run [scheduler] startup_agent_delay_seconds (default 120) after boot; see Scheduling.
  • Stopping. A stop drains active turns for up to 30 s, then cancels the rest (drain_budget_ms in agentos gateway status --json); the service units allow 54 s (the worst-case stop plus a margin) before they kill. Stop a service-run gateway through the service (agentos gateway stop tells you how) or remove it with agentos gateway uninstall.

Diagnostics

Diagnostics help explain runtime behavior without changing the core task.

agentos diagnostics status
agentos diagnostics on
agentos diagnostics off

Use diagnostics when investigating:

  • provider retry behavior;
  • router decisions;
  • cache breaks;
  • compaction events;
  • tool-result compression;
  • channel delivery failures.

Turn diagnostics off after collecting the needed evidence.

For diagnostics guidance and safe sharing notes, see Diagnostics and Replay.

Replay

Replay a recorded turn from the decision log:

agentos replay --session <session-key> --turn <turn-id>

Replay is useful for reproducing an agent turn, reviewing decision metadata, or debugging behavior after the original chat has moved on.

Migration

Preview first:

agentos migrate openclaw --json
agentos migrate hermes --json

Apply after reviewing the report:

agentos migrate openclaw --apply
agentos migrate hermes --apply

See MIGRATION.md for custom paths and conflict handling.

MCP Server

AgentOS can run an MCP server bridge:

agentos mcp-server run

The MCP SDK is a core dependency, so a standard install from the Installation section of the README is enough; there is no mcp extra.

Use this when another MCP-capable client should access AgentOS-managed tools or runtime surfaces.

For setup details, see MCP Server Bridge.

Install Inventory

Emit a reproducible workspace-state inventory:

agentos dist
agentos dist --output workspace-state.json
agentos dist -o ./support/workspace-state.json

With no flags the payload prints to stdout. --output (-o) writes the payload to the given file instead (creating parent directories) and prints the resolved path so shell pipelines can capture it.

The payload is a versioned JSON document:

{
  "schema_version": 1,
  "agentos_version": "<installed version>",
  "python_requires": ">=3.12",
  "bundled_channels": ["discord", "email", "slack", "telegram", ...],
  "bundled_tools": ["agents", "code_exec", "filesystem", "git", ...],
  "gateway_defaults": {"listen": "127.0.0.1", "port": 18791}
}

It is built only from installed package metadata plus hard-coded constants, so two calls from the same install produce byte-identical JSON (sorted keys, stable indent). It carries no environment values, file paths, timestamps, or secrets — safe to attach to support requests.

Use this for support, release QA, or environment comparison.

Models

Inspect available models:

agentos models list

In this build, model inspection can be runtime-backed. If it cannot connect, start the gateway first:

agentos gateway run

For provider catalog inspection that does not require a live gateway, use:

agentos providers list

Read: Providers and Models

Health Checklist

For a confusing install or runtime:

agentos doctor
agentos gateway status
agentos gateway status --deep --json
agentos providers list
agentos search list
agentos channels types
agentos sandbox status

Then turn on diagnostics only if the basic health surfaces are not enough.