{"id":50743024,"url":"https://github.com/zackiles/agent-runtime","last_synced_at":"2026-06-10T18:31:05.398Z","repository":{"id":361898244,"uuid":"1212953431","full_name":"zackiles/agent-runtime","owner":"zackiles","description":"Agent Runtime — CLI, control plane, and SDKs for deploying and running autonomous agents","archived":false,"fork":false,"pushed_at":"2026-06-10T16:36:00.000Z","size":64749,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-10T17:20:52.569Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zackiles.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY-TODO.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-16T22:38:20.000Z","updated_at":"2026-06-10T16:37:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zackiles/agent-runtime","commit_stats":null,"previous_names":["zackiles/agent-runtime"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/zackiles/agent-runtime","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zackiles%2Fagent-runtime","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zackiles%2Fagent-runtime/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zackiles%2Fagent-runtime/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zackiles%2Fagent-runtime/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zackiles","download_url":"https://codeload.github.com/zackiles/agent-runtime/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zackiles%2Fagent-runtime/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34165482,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-10T18:31:04.645Z","updated_at":"2026-06-10T18:31:05.389Z","avatar_url":"https://github.com/zackiles.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Agent Runtime\n\nDeploy, manage, orchestrate and observe your own enterprise-grade AI gateway and\nheadless agent runtime on GCP. An agentic infrastructure platform optimized for\nspeed of delivery in the strictest of environments and a fantastic UX for\ntechnical and non-technical users alike.\n\n\u003e [!NOTE]\n\u003e The control plane uses **SQLite** with GCS backup for its database. This\n\u003e keeps infrastructure simple and cost-effective but limits the control plane\n\u003e to a single Cloud Run instance. When horizontal scaling is needed, a\n\u003e distributed database (e.g. Turso, Cloud SQL, Firestore) will replace SQLite.\n\n## Prerequisites\n\n- A GCP project with Cloud Run, Cloud Functions, Secret Manager, and Cloud\n  Scheduler APIs enabled\n- A service account with appropriate roles\n- (Optional) A VPC connector if agents need private network access\n- The `gcloud` CLI installed and authenticated\n\n## Install\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/zackiles/agent-runtime/main/install.sh | sh\n```\n\nThis detects your platform and installs the `ar` binary to `/usr/local/bin`. Set\n`INSTALL_DIR` to change the location:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/zackiles/agent-runtime/main/install.sh | INSTALL_DIR=~/.local/bin sh\n```\n\nOr install a specific version:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/zackiles/agent-runtime/main/install.sh | sh -s -- v0.1.0\n```\n\nYou can also download a binary directly from\n[Releases](https://github.com/zackiles/agent-runtime/releases). Builds are\navailable for Linux (x64, arm64) and macOS (x64, arm64).\n\nOn first run, `ar` creates a `~/.ar/` directory with the following structure:\n\n```\n~/.ar/\n  settings.jsonc    # GCP project settings (created by ar init)\n  secrets.jsonc     # Local secrets\n  data/             # SQLite databases (one per tenant)\n  registry/         # Your private registry entities\n    agents/\n    tools/\n    skills/\n    rules/\n```\n\n\u003e [!TIP]\n\u003e Run `ar init` to configure your GCP project, or set `AR_PROJECT`,\n\u003e `AR_REGION`, and `AR_RUNTIME_ACCOUNT` as environment variables. See\n\u003e [CONFIG.md](CONFIG.md) for all options and authentication setup including\n\u003e CI/CD with GitHub Actions OIDC.\n\n## AI Skill (Claude Code CLI / Cursor CLI)\n\nInstall the Agent Runtime skill to give Claude Code or Cursor full knowledge of\nthe CLI, architecture, commands, and deployment workflows:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/zackiles/agent-runtime/main/skill/install.sh | sh\n```\n\nThis installs the skill to `~/.claude/skills/agent-runtime/` and\n`~/.cursor/skills/agent-runtime/`. Once installed, invoke it with\n`/agent-runtime` in Claude Code or `@agent-runtime` in Cursor. The skill can\nguide an agent through installing the CLI, configuring GCP, deploying a control\nplane, and managing agents — including all command flags and options.\n\n## Getting Started\n\nThe fastest way to get started is `ar quickstart`, which walks you through the\nentire setup interactively:\n\n```bash\nar quickstart\n```\n\nOr do it step by step:\n\n### 1. Initialize and Deploy\n\n```bash\nar deploy my-agent\n```\n\nIf no registry exists, `ar deploy` will prompt you to set up your GCP project,\ndeploy the control plane, scaffold the agent, and deploy it — all in one\ncommand. Subsequent deploys skip the setup steps.\n\n### 2. Test the Agent\n\n```bash\nar run my-agent --data '{\"message\": \"hello\"}'\n```\n\nInvokes the deployed agent and prints the response. For quick experiments\nwithout creating a persistent agent:\n\n```bash\nar run --inline 'return { message: \"hello from \" + AgentEnvironment.instance.tenant }'\n```\n\n### 3. Check Status\n\n```bash\nar status        # registry overview\nar list          # deployed agents\nar logs my-agent # agent logs\n```\n\n## Commands\n\n| Command                        | Description                                    |\n| ------------------------------ | ---------------------------------------------- |\n| `ar init`                      | Initialize the agent registry                  |\n| `ar create \u003cid\u003e[@version]`     | Scaffold a new agent                           |\n| `ar deploy \u003cid\u003e[@version]`     | Deploy an agent (creates if needed)            |\n| `ar run \u003cid\u003e [--data \u003cjson\u003e]`  | Invoke a deployed agent                        |\n| `ar run --inline \u003ccode\u003e`       | Deploy, invoke, and clean up a one-liner agent |\n| `ar quickstart`                | Guided setup: init, control plane, first agent |\n| `ar logs \u003cid\u003e`                 | Fetch agent logs                               |\n| `ar list`                      | List deployed agents                           |\n| `ar destroy \u003cid\u003e`              | Destroy an agent                               |\n| `ar clear-builds [slug]`       | Remove old builds (one agent or all)           |\n| `ar status`                    | Registry overview with public/private items    |\n| `ar connect \u003curl\u003e`             | Connect to a control plane                     |\n| `ar disconnect`                | Switch to local mode                           |\n| `ar copy \u003cslug\u003e --to \u003ctenant\u003e` | Copy agent and dependencies across tenants     |\n| `ar cp deploy`                 | Deploy the control plane                       |\n| `ar cp sync`                   | Sync default registry to all tenants           |\n| `ar cp destroy`                | Remove the control plane Cloud Run service     |\n| `ar cp destroy --all`          | Full teardown of all AR resources from GCP     |\n| `ar cp reset`                  | Reset tenant data (keep infrastructure)        |\n| `ar bot enable`                | Enable the Slack bot on the control plane      |\n| `ar bot disable`               | Disable the Slack bot                          |\n| `ar bot status`                | Show Slack bot status                          |\n\n### Agent Lifecycle\n\n```bash\nar agent create \u003cid\u003e[@version]      # scaffold with template\nar agent deploy \u003cid\u003e[@version]      # deploy agent (container or source mode)\nar agent run \u003cid\u003e [--data \u003cjson\u003e]   # invoke deployed agent\nar agent logs \u003cid\u003e                  # fetch logs\nar agent list                       # list all agents\nar agent destroy \u003cid\u003e               # destroy agent and triggers\nar agent clear-builds [slug]       # remove old builds (one agent or all)\nar agent clear-builds --force      # clear all without confirmation (CI)\nar agent switch \u003cslug\u003e \u003cversion\u003e    # set active version\n```\n\n### Deploy Modes\n\nAgent Runtime supports two deployment architectures, selected during first\n`ar cp deploy`:\n\n| Mode          | Default | How it works                                                                                                                                                         |\n| ------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Container** | Yes     | Agents deploy as Cloud Run services from container images. Tool binaries are baked into a shared base image. Rules and skills are served via GCS FUSE. ~10s deploys. |\n| **Source**    | No      | Agents deploy as Cloud Functions via Cloud Build. Each deploy takes 2-5 minutes. Simpler setup (no Artifact Registry).                                               |\n\nContainer mode is recommended. See\n[docs/deploying.md](docs/deploying.md) for details on both modes.\n\n### Agent I/O: Consumes From and Publishes To\n\nEvery agent has a directed graph of **edges** that define how it receives input\n(consumes from) and where it sends output (publishes to). Edges are stored in\nthe `agent_edge` table and each references a backing configuration (webhook,\ncron schedule, Pub/Sub topic, etc.).\n\n**Ingress (Consumes From):**\n\n| Type      | Description                                                                  |\n| --------- | ---------------------------------------------------------------------------- |\n| `webhook` | HTTP endpoint with a crypto-random URL path segment. Default for all agents. |\n| `pubsub`  | GCP Pub/Sub topic subscription via Eventarc.                                 |\n| `cron`    | Scheduled invocation via Cloud Scheduler (cron expression + timezone).       |\n\n**Egress (Publishes To):**\n\n| Type      | Description                                               |\n| --------- | --------------------------------------------------------- |\n| `webhook` | HTTP callback to an external URL. Default for all agents. |\n| `pubsub`  | Publish output to a GCP Pub/Sub topic.                    |\n| `gcs`     | Write output to a Cloud Storage bucket/path.              |\n| `slack`   | Send output as a Slack message to a channel or user.      |\n\nAn agent can have **multiple** edges of the same or different types in each\ndirection. When no edges are specified during creation, a default webhook pair\n(one ingress, one egress) is created automatically.\n\nWebhook ingress URLs use crypto-random UUIDs as path segments, making them\ninfeasible to brute-force. They are not public endpoints by default and require\nthe agent to be deployed before they accept traffic.\n\n```bash\nar trigger create my-agent --type cron --schedule \"0 */6 * * *\"\nar trigger create my-agent --type pubsub --topic orders\n```\n\nEdges are configured through the web dashboard (Agents \u003e New Agent \u003e Ingress \u0026\nEgress section), the Slack bot (`/ar create-agent`), or the control plane\nAPI (`POST /api/agents` with an `edges` array).\n\n### Registry Entities\n\nAgents can use tools, skills, and rules from the registry. Each entity type has\na file-based specification with a manifest JSON, `README.md` with YAML\nfrontmatter, and versioned folders. By default all entities are created in your\nprivate registry. Use `--public` to publish to the shared public registry\n(admin-only when protected).\n\n```bash\nar tool create \u003cname\u003e [--public]    # scaffold tool folder + DB record\nar tool deploy \u003cslug\u003e               # validate, compress, upload to GCS\nar tool destroy \u003cslug\u003e              # remove from registry DB\nar tool list [--public]\nar tool clone \u003cslug\u003e\n\nar skill create \u003cname\u003e [--public]\nar skill deploy \u003cslug\u003e\nar skill destroy \u003cslug\u003e\nar skill list [--public]\nar skill clone \u003cslug\u003e\n\nar rule create \u003cname\u003e [--public]\nar rule deploy \u003cslug\u003e\nar rule destroy \u003cslug\u003e\nar rule list [--public]\nar rule clone \u003cslug\u003e\n```\n\n### Secrets and Triggers\n\nSecrets are synced to GCP Secret Manager during `ar cp deploy`. See\n[Deploying: Secrets](docs/deploying.md#secrets) for configuration details.\n\nYou can also manage secrets individually:\n\n```bash\nar secret set \u003cname\u003e \u003cvalue\u003e [--agent \u003cagent-id\u003e]\nar secret remove \u003cname\u003e [--agent \u003cagent-id\u003e] [--force]\nar secret list\n\nar trigger create \u003cagent-id\u003e --type \u003ccron|pubsub\u003e\nar trigger remove \u003cagent-id\u003e \u003ctrigger-name\u003e [--force]\nar trigger list \u003cagent-id\u003e\n```\n\n### Teams and Departments\n\nTeams and Departments are a way to tag and logically group sets and supersets of\nagents, allowing composibility and orginization of large agent deployments. In\nthe future they will also support consensus models where multi-agent and or\nmulti-team output is voted on and continously guided by a higher-order set of\nvalues or rules.\n\n```bash\nar team create \u003cname\u003e [--department \u003cdept\u003e]\nar department create \u003cname\u003e\n```\n\n## Slack Bot\n\nAgent Runtime includes a Slack bot that lets users interact with agents directly\nfrom Slack. After deploying the control plane, enable the bot with:\n\n```bash\nar bot enable\n```\n\nThe CLI walks you through Slack app creation, credential configuration, and\nmanifest setup. The bot runs inside the control plane -- no separate service.\n\nOnce deployed, users enroll at `https://{cp-url}/web/me` to link their Google\nWorkspace identity to Slack. Then they can interact with agents using:\n\n- `/ar help` — slash command (works in any channel)\n- `/ar run {agent} {input}` — run an agent\n- `/ar list` — list accessible agents\n- DM the bot directly with `help`, `list`, `status`, or any message to run the\n  default agent\n\nSee [`docs/slack-bot.md`](docs/slack-bot.md) for the full setup guide including\nSlack app configuration, user enrollment, and troubleshooting.\n\n## Tenants\n\nTenants are logical environments. `development` (default) and `production` are\ncreated automatically. Agents can be copied across tenants easily, including all\nof the registry items their dependant on. Only files and secrets aren't\nautomatically copyable.\n\n| Selection         | Tenant           |\n| ----------------- | ---------------- |\n| Default           | `development`    |\n| `--production`    | `production`     |\n| `--tenant \u003cname\u003e` | Any named tenant |\n\n## Global Flags\n\n| Flag                | Effect                                                |\n| ------------------- | ----------------------------------------------------- |\n| `--registry \u003cpath\u003e` | Override registry folder (default: `~/.ar/registry/`) |\n| `--tenant \u003cname\u003e`   | Target a specific tenant                              |\n| `--production`      | Shortcut for `--tenant production`                    |\n| `--public`          | Target the public registry                            |\n| `--version \u003cver\u003e`   | Target a specific agent version                       |\n| `--force`           | Skip confirmation prompts                             |\n| `--json`            | Output raw JSON                                       |\n\n## Environment Variables\n\n| Variable               | Purpose                                              |\n| ---------------------- | ---------------------------------------------------- |\n| `AR_HOME`              | Override home directory (default: `~/.ar/`)          |\n| `AR_REGISTRY`          | Override registry path (default: `~/.ar/registry/`)  |\n| `AR_DB_PATH`           | Override database directory (default: `~/.ar/data/`) |\n| `AR_CONTROL_PLANE_URL` | Control plane URL (enables remote mode)              |\n| `AR_AGENT_DEPLOY_MODE` | Deploy mode: `container` (default) or `source`       |\n| `AR_AUTH_METHOD`       | Auth method: `user` (default) or `adc`               |\n| `AR_PROJECT`           | GCP project ID                                       |\n| `AR_REGION`            | GCP region                                           |\n| `AR_RUNTIME_ACCOUNT`   | Runtime account email                                |\n| `AR_WORKER_ACCOUNT`    | Worker service account email                         |\n| `AR_TENANT`            | Named tenant to target                               |\n| `AR_USER`              | Override current user email                          |\n| `AR_ADMIN_GROUP`       | Comma-separated admin emails                         |\n\n## Modes\n\n| Mode   | When                                 | Behavior                                |\n| ------ | ------------------------------------ | --------------------------------------- |\n| Local  | Default (no control plane)           | Uses `gcloud` CLI + local SQLite        |\n| Remote | After `ar connect` or `ar cp deploy` | Operations go through the control plane |\n| Server | `AR_MODE=server`                     | Runs the control plane itself           |\n\n## Agent Runtime Library\n\nAgent functions have access to a set of globals bootstrapped by the runtime\nlibrary. See [`sdk-agent-nodejs/README.md`](sdk-agent-nodejs/README.md) for the\nfull API.\n\n| Class              | Purpose                                |\n| ------------------ | -------------------------------------- |\n| `AgentStorage`     | Read/write files to GCS                |\n| `AgentTools`       | Execute tools via stdio                |\n| `AgentSession`     | Request context (auth, headers, body)  |\n| `AgentEnvironment` | Agent metadata (tenant, version, team) |\n| `AgentSecurity`    | PII detection and sanitization         |\n| `AgentSecrets`     | Secret management                      |\n| `AgentAudit`       | Audit trail and structured logging     |\n\n## Web Dashboard\n\nThe control plane ships with a web dashboard for managing agents, monitoring\nthe runtime, and administering tenants. It runs inside the Cloud Run service\nalongside the API — no separate deployment.\n\n### System Overview\n\nThe system page gives admins a single-screen snapshot of the running\ninfrastructure: build version, GCP project, Cloud Run revision and scaling\nconfig, service accounts, and tenant storage stats.\n\n![System overview](docs/assets/web-system.png)\n\n### Agents\n\nList, filter, and manage deployed agents. Expand any row for edge details,\nteam, department, and quick actions (edit, deploy, delete).\n\n![Agents](docs/assets/web-agents.png)\n\nThe agent builder provides a full-featured creation form with configurable\ningress/egress edges (webhook, Pub/Sub, cron, GCS, Slack), a markdown prompt\neditor with template variable support, and team/department assignment.\n\n![Agent builder](docs/assets/web-agents-builder.png)\n\n### Registry\n\nBrowse agents, tools, skills, and rules across public and private registries.\nAdmins can view promotable items pending publication to the shared catalog.\n\n![Registry](docs/assets/web-registry.png)\n\n### Telemetry\n\nSearch, filter, and trace telemetry events across the platform. Filter by time\nrange, log level, and client. Click a trace ID to see the full span waterfall\nfor a single request.\n\nExternal apps post events to `POST /telemetry` with a **telemetry API key** in\nthe `X-Telemetry-Key` header. Mint a key on the **Clients** tab of the telemetry\npage — the plaintext key is shown only once. Reading telemetry and managing\nclients stay admin-only. See [docs/telemetry.md](docs/telemetry.md) for the key\nformat and full ingest/query reference.\n\n![Telemetry](docs/assets/web-telemetry.png)\n\n### Audit Log\n\nAn immutable record of every entity change: creates, updates, deploys, deletes,\nand copies. Filter by entity type and action, expand any row for full metadata.\n\n![Audit log](docs/assets/web-audit.png)\n\n### Settings\n\nTenant-level administration: manage admins and roles, view tenant storage and\ntraffic stats, rotate secrets, and download SQLite backups.\n\n![Settings](docs/assets/web-settings.png)\n\n### Artifacts\n\nAdmin-only view of the GCP Artifact Registry. Browse Docker images grouped by\npackage with version digests, tags, sizes, and build times. Delete packages or\nindividual versions. Clear old builds per agent to free up GCP resources while\nkeeping the latest deployed version. View Cloud Build history with status,\nduration, and result hashes. Open build logs inline.\n\n![Artifacts — Images](docs/assets/web-artifacts.png)\n\nThe Builds tab shows recent Cloud Build runs with color-coded status badges,\nbuild duration, output image tags, and result digests.\n\n![Artifacts — Builds](docs/assets/web-artifacts-builds.png)\n\nClick \"Logs\" on any build to open a modal with the full Cloud Build output\nshowing each step (fetch, build, push).\n\n![Artifacts — Build Logs](docs/assets/web-artifacts-logs.png)\n\n## Development\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for the full development guide covering\nbuilding from source, architecture, testing, and the web dashboard. See\n[`web/README.md`](web/README.md) for web dashboard architecture, code style, and\ndevelopment workflow.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzackiles%2Fagent-runtime","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzackiles%2Fagent-runtime","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzackiles%2Fagent-runtime/lists"}