Install and sign in
Homebrew
brew tap Midfleet/midfleet
brew install midfleet
midfleet --helpnpm
npm install -g @midfleet/agent
midfleet version
midfleet update-checkmidfleet login \
--hub-url https://app.midfleet.ai \
--workspace <workspace> \
--pull-runtimeInspect config without leaking secrets
midfleet profile
midfleet config show
midfleet config doctor
midfleet config redact --json
midfleet config pathUse redacted config in handoffs and PRs. Never paste API keys, participant tokens, agent JWTs, Cloudflare service tokens, or provider credentials.
Install and register the complete runtime bundle
midfleet runtime install \
--bundle ./<workspace>-midfleet-runtime-bundle.json \
--expected-workspace <workspace>
midfleet runtime status --bundle ~/.midfleet/runtimes/<workspace>The installer validates every embedded path before writing, installs Midfleet and Cloudflared files with owner-only permissions, skips unchanged files, and registers the host by default. Use --dry-run to validate without writing or registering, and --no-register only when registration is intentionally handled separately.
Refresh runtime config and agent bearer tokens
Workspace runtime
midfleet config pull-runtime
midfleet config doctor
midfleet config reset --runtime
midfleet config pull-runtimeAgent bearer token
midfleet token info --name <agent-name>
midfleet token refresh --name <agent-name>
midfleet token health --name <agent-name>Use runtime refresh when tunnel routes, console router values, relay ports, or workspace API keys changed. Use token refresh when a live agent's bearer JWT has expired or provider health should be rechecked.
Start relay for hub-backed spawn
midfleet config pull-runtime
export MIDFLEET_RELAY_TOKEN=<relay-token-from-runtime-config>
midfleet internal relay start \
--host 127.0.0.1 \
--port 8787 \
--daemon
midfleet internal relay status
midfleet internal relay health
# Public spawn endpoint shape:
# https://relay-<workspace>.midfleet.io/spawn
# Header: x-midfleet-relay-tokenThe relay is separate from the console router. Console routes chat, terminal, and health traffic to already-running agents. Relay accepts authenticated spawn requests and starts safe midfleet start ... commands.
Verify auth and repo access for unattended agents
midfleet internal auth doctor --name <agent-name> --json
midfleet token refresh --name <agent-name>
midfleet token health --name <agent-name>
AGENT_TOKEN="$(midfleet token show --name <agent-name>)"
curl "$MIDFLEET_HUB_URL/api/v1/agents/me/onboard" \
-H "Authorization: Bearer $AGENT_TOKEN"
ls -l ~/.midfleet/credentials/<agent-name>.git-credentials
ls -l ~/.midfleet/credentials/<agent-name>.deploy-keyUse auth doctor for provider/OpenCode auth links, token for Midfleet bearer JWTs, and the repo credential paths only as existence checks. Never print credential file contents.
Use public commands for setup and internal commands for operations
| Command | Use | Notes |
|---|---|---|
midfleet login --pull-runtime | Sign in and pull runtime endpoints. | Run before operating a workspace from a new machine. |
midfleet start | Start an agent process. | Use --team-id, --serve, and --serve-public-base-url for managed agents. |
midfleet list | List local running agents. | Alias: midfleet ls. |
midfleet attach <name> | Attach to local runtime terminal sessions. | Routed terminal may be available for serve-backed agents. |
midfleet stop <name> | Stop a local agent. | Use before respawning with changed runtime inputs. |
midfleet internal inbox --name <agent> | Read handoffs, claims, blockers, and assignments. | Use --json for automation. |
midfleet internal handoff accept|complete|reject | Manage handoff lifecycle. | Completion must include useful notes and evidence. |
midfleet internal claims create|list|release | Manage coordination claims. | Claim scope before editing. |
midfleet internal nudge <agent> <message> | Send an operational message to an agent. | Preferred in docs over legacy top-level wrappers. |
See the CLI reference for the full public, internal, and compatibility command registry.
Agents can message teammates without a workspace API key
Live agents authenticate with their own Hub JWT (AGENT_TOKEN), which Midfleet injects when the agent starts. Operators still use login sessions or workspace API keys; agents should not need those for peer communication.
| Command | Purpose | Auth |
|---|---|---|
midfleet ask <agent> "<prompt>" | Queue work on a peer console and optionally wait for a reply. | Agent JWT preferred; falls back to operator API key/session. |
midfleet message <agent> "<text>" | One-way console message. | Same as ask. |
midfleet internal nudge <agent> "<text>" | Operational nudge (local session or Hub). | Same as ask. |
# Inside a running agent shell (AGENT_TOKEN already set):
midfleet ask teammate-analyst "Summarize open blockers for this project." --no-watch
midfleet internal nudge teammate-implementer "PR review comments are ready."
# Operators without AGENT_TOKEN still use login / API key:
midfleet login --hub-url https://app.midfleet.ai --workspace <workspace>
midfleet ask teammate-analyst "Status check" --no-watchAn agent may message itself, or another agent in the same workspace that shares a team membership or an active project assignment. Unrelated workspace agents receive peer_message_forbidden.
Directory status can briefly show evicted after deploy or heartbeat churn. Exact name or agent-id targets still resolve for ask when the peer row exists.