Skip to content

guide.md

Latest commit

 

History

History
166 lines (132 loc) · 7.55 KB

guide.md

File metadata and controls

166 lines (132 loc) · 7.55 KB
Raw

Installation and operation

Back to Managoat Sprite

Installation

To create the Sprite, clone a project, and bootstrap it from your computer, use the host provisioning CLI. The steps below install the service on a Sprite you already have. These service commands use managoat inside the Sprite; the host command on your computer is manasprites. For prerequisites and connection options, see the manual installation walkthrough.

The Codex path has passed installation and real inference checks on a clean Sprite, including the existing chat template's HTTP/SSE client. v0.1.0 provides preview release archives for Linux AMD64 and ARM64. Claude qualification remains pending. Run inside your Sprite with an inference key already exported:

curl -fsSL https://raw.githubusercontent.com/managoat/manasprites/v0.1.0/install.sh | sh -s -- \
  --runtime codex --credential-env OPENAI_API_KEY --workspace /home/sprite/project

Or use --credential-file /path/to/key to read a plain API-key file. --runtime claude uses ANTHROPIC_API_KEY. The installer downloads a checksummed Linux release containing Erlang, installs pinned agent tools in an application-owned home, registers a Sprite Service, and checks authenticated HTTP readiness. It does not require a Fountain account, external database, or build tools. Before saving credentials, installation checks writable paths, disk reserve, port availability and service ownership. It reports named failures such as port_unavailable, workspace_invalid and service_name_conflict.

The application key is generated locally (or supplied as MANAGOAT_API_KEY):

managoat status
managoat key show

The Sprite's platform URL authentication is separate from the application key. For a direct URL-plus-key endpoint, configure the Sprite URL with public platform access during provisioning. Managoat's API still requires its bearer key. For private development, use sprite proxy 8080 from the provisioner's computer. The installer never needs an organization-wide Sprites token.

API

curl "$BASE_URL/api/conversations" \
  -H "Authorization: Bearer $MANAGOAT_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: first-conversation' \
  -d '{"agent_id":"default","prompt":"Inspect this project and explain how to run it."}'

curl -N "$BASE_URL/api/conversations/$CONVERSATION_ID/stream?blocks=true" \
  -H "Authorization: Bearer $MANAGOAT_API_KEY"

curl "$BASE_URL/api/conversations/$CONVERSATION_ID/prompts" \
  -H "Authorization: Bearer $MANAGOAT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"Now run its tests."}'

The API includes agents, conversations, turns, paginated events, global and conversation SSE, interruption, termination, deletion, and permission answers. GET /api/capabilities describes the supported Fountain subset. Bearer auth applies to all API routes. Configure explicit cors_origins to use a browser client such as fountain-template-chat in API-key mode.

One configured agent and one shared workspace serve multiple conversations. One turn runs at a time. Deleting a conversation preserves your Sprite and project files. The service and agent share the same trust boundary; the agent has access to the computer on which you install it.

Conversations retain an immutable reference to their runtime, workspace and system instructions. A follow-up fails with configuration_changed if those have changed. Restore the original definition or explicitly start a new conversation. Model selection and effective permissions are recorded per turn; tightening installation permissions also tightens subsequent follow-up turns.

Persistence and operation

The default application root is ~/.local/share/managoat; MANAGOAT_ROOT overrides it. Configuration is config/config.json, the application key is config/client.key, and SQLite is state/managoat.sqlite3. Secrets are stored in private files and are excluded from ordinary command output.

status --json separates installation state, API reachability, runtime availability, admission capacity and external access. agent_initialization: verified_at_install reports a successful local handshake against the recorded adapter executable; provider credentials are verified only by an explicit inference probe. A busy turn does not make the API unhealthy. An exhausted disk reserve produces an authenticated readiness response with its failure reason. An unreachable API leaves process_running unknown rather than claiming the process has stopped.

If an established database is missing or empty, startup refuses to create a replacement. Restore a backup to recover history.

The subprocess bridge and ACP input enforce a 1,024-message overload threshold. An overloaded turn stops with output_backpressure_exceeded. This is separate from the configured maximum output size per turn: a fast producer can reach the queue threshold before reaching that size limit.

A browser disconnect does not cancel work. Active turns hold a finite Sprite task that is renewed while they run. Idle SSE clients should disconnect when they have nothing to follow, since reconnecting clients can keep a Sprite awake.

After a service crash, history survives and ambiguous in-flight turns are marked interrupted. An explicit follow-up resumes the saved runtime session. The service does not automatically replay a prompt that may already have caused external effects. It does not promise seamless mid-turn reattachment.

managoat status [--json]
managoat doctor [--inference]
managoat logs
managoat start | stop | restart
managoat key show | rotate
managoat configure --file config.json
managoat backup --output backup.tar.gz [--workspace]
managoat restore --input backup.tar.gz --credential-file /path/to/key [--workspace PATH]
managoat upgrade --version VERSION
managoat uninstall

doctor --inference makes a small paid model request. A normal readiness check only establishes local agent initialization. Backups omit application and inference credentials by default. Uninstall preserves state and the workspace. Restore requires empty application state and supplies a new application key. Backup archives remain sensitive because transcripts and workspace files can contain private content. Idempotency deletion tombstones are retained indefinitely in this version; events are not automatically pruned.

The service uses a small Linux supervisor to restart the BEAM after crashes and reap orphaned tools before accepting more work. Upgrades stage and validate an archive before stopping the API, save a consistent database backup, and restore the previous release and database if migration or readiness fails. Automatic upgrades currently support schema 1 only.

Development

mix deps.get
mix check
python3 -m unittest discover -s test -p '*_test.py' -v

Linux release: sh scripts/build-release.sh. The release workflow builds AMD64 and ARM64 archives on Ubuntu 24.04. The local test suite exercises a real ACP peer against the libraries' ScriptedAgent and executes real subprocesses.

To test an installation using the existing chat template client (paid inference):

FOUNTAIN_CLIENT_ROOT=/path/to/fountain-template-chat \
MANAGOAT_BASE_URL=http://localhost:8080 \
MANAGOAT_KEY_FILE=/path/to/client.key \
bun scripts/check-client.ts

This check expects http://localhost:5173 in the installation's cors_origins.

The specification defines the full release target; integration verification is recorded in the acceptance record.

Apache-2.0.