Skip to content

agents.md

Latest commit

 

History

History
107 lines (70 loc) · 6.06 KB

agents.md

File metadata and controls

107 lines (70 loc) · 6.06 KB
Raw
title Working with AI agents
description Connect an AI coding agent to your instance, scope its token, and give it the instructions it needs to deploy safely.
og:url https://docs.levelrail.com/agents

An agent talks to the platform the way you do: through the CLI (levelrail-cli) or the MCP server (levelrail-mcp). Everything it does goes through the normal API with the token you give it, so its access is exactly that token's abilities, and every change lands in the audit log under the agent's name.

Set up a project with init

Run this in the project root:

levelrail-cli init

It detects the stack and writes three files:

File What it is
app.yaml The app spec, validated with the same parser the control plane uses before it is written.
AGENTS.md Instructions for an agent: deploy, wait, read a failure, roll back, set env and secrets safely. Uses the CLI name you ran and your API URL when the CLI knows it.
.mcp.json A stdio MCP server entry. The token is an env var reference (${APP_API_TOKEN}), never a value.

Detection order: Dockerfile, compose file, package.json (Next.js, NestJS, Express, Fastify, Vite), go.mod, Java (pom.xml, Gradle), Python (requirements.txt, pyproject.toml, Pipfile), then a plain index.html static site. Provider names match the build system's own, so what init reports lines up with what a deploy will detect. Nothing from the project is executed.

Flags:

  • --dry-run shows the plan and changes nothing.
  • --force overwrites files that already exist. Without it existing files are skipped, and the diff of what would change is shown.
  • --yes skips the confirmation prompt. A script without a terminal must pass --yes or --dry-run.
  • --json prints the plan and result as one JSON value.
  • --mode picks the tool exposure written to .mcp.json: agent-core (default), read-only, standard or full.
  • --dir, --api-url, --profile and --mcp-binary override the directory, the URL written into the files, the credentials profile and the MCP binary name.

Install the skill

The repository ships an agent skill that covers the deploy, wait, diagnose and roll back loop, so an agent follows the safe path without you pasting in instructions:

npx skills add https://github.com/glincker/levelrail --skill levelrail

Then ask your agent: "Deploy this repo to my Levelrail and tell me when it is live." The skill makes it block on levelrail-cli apps wait <app>, whose exit code (and --json outcome) says whether that exact deploy converged.

levelrail-cli init writes the same guidance into a project's own AGENTS.md, filled in with that project's app name and API URL.

Modes

The MCP server exposes a subset of its tools depending on the mode. Each mode loads a different slice of the tool list into the client context.

Mode Tools Use it for
agent-core (a tool profile, --tool-profile agent-core) 15 Shipping and debugging one app. The default for init.
read-only over 240 tools in on-demand toolsets Observers that must not change anything.
standard over 240 tools in on-demand toolsets Read and mutating tools, no destructive ones.
full over 240 tools in on-demand toolsets Every tool, including destructive ones.

Exact per-toolset counts are in MCP tool surface; Agent tooling audit explains how token costs are measured.

Tokens

Give each agent its own token so its actions are attributable and it can be revoked alone.

levelrail-cli tokens create --name ci-agent --preset deployer --agent "Claude Code"

--preset takes observer, deployer or operator (see the table below); --abilities sets an explicit list instead.

The --agent label is shown on the tokens page and recorded on every audit entry the token makes. Filter the audit log by it with audit-log --agent NAME or the agent chip on the audit log page. Settings > Agents in the dashboard shows the MCP connect snippet (copyable, per mode), lists agent tokens with their last used time, and has a "Create agent token" flow with the same three presets:

Preset Abilities Can do
Read-only observer read Look at apps, logs, metrics and deploys.
Deployer read, deploy Also trigger deploys and rollbacks.
Full operator read, read:sensitive, write, write:sensitive, deploy Also change config, env vars, domains and secrets. Never root.

The token is shown once, when it is created. Store it in your shell profile or secret manager as APP_API_TOKEN, not in the repo.

Read logs by level

The app Logs page (Search tab) shows a chip per level (error, warn, info, debug) with the number of loaded lines at that level, and a "Showing N of total" line. Each row has a gutter with an icon and the level word, so the level does not depend on color. The search loads the newest 1,000 matches; the total counts every match in the range. Agents get a capped excerpt of the same data from levelrail-cli logs query or the MCP query_logs tool, which filter by level, time window and text.

Dry run before changing anything

  • plan_change (MCP) previews a single mutating tool call without running it, and plan_apply previews a resource file. levelrail-cli apply --dry-run is the CLI form.
  • levelrail-cli apps preflight NAME checks DNS, ports, disk, the image and required env before a deploy.

Wait for a deploy

An agent should never assume a deploy worked. wait_for_deploy (MCP) or levelrail-cli apps wait NAME blocks until the deploy converges and reports success or the structured failure. On failure, read it with levelrail-cli apps deploys show NAME DEPLOY_ID, fix one thing, and retry. Roll back first if production is down.

Next steps

Run levelrail-mcp over stdio or HTTP and scope its token.

Token cost per mode and the budget tests.