Getting Started

This guide assumes ato-cli v0.3 and LIFECYCLE_SPEC v1.2, showing the shortest path to create and run a new Capsule.

Prerequisites

Section titled “Prerequisites”
  • ato command available
  • Local working directory with write access
  • For signing: write access to ~/.capsule/keys
Terminal window
ato --help
ato engine features

Engine Setup

Section titled “Engine Setup”

The standard procedure for Source runtime is ato setup --engine nacelle. For existing binaries, use ato engine register.

Terminal window
ato setup --engine nacelle
ato engine register --name nacelle --path /usr/local/bin/nacelle --default

Create a New Capsule

Section titled “Create a New Capsule”

Use ato new for template generation. Available templates: python|node|hono|rust|go|shell.

Terminal window
ato new hello-capsule --template node
cd hello-capsule

Minimal capsule.toml (v0.2) example:

schema_version = "0.2"
name = "hello-capsule"
version = "0.1.0"
type = "app"
default_target = "cli"


[targets.cli]
runtime = "source"
entrypoint = "node index.js"

Validate and Run

Section titled “Validate and Run”
  1. Validate manifest - ato validate . checks syntax/semantics/IPC conflicts.
  2. Run capsule - ato open . executes default_target.
  3. Monitor process - ato ps / ato logs / ato close for management.
Terminal window
ato validate .
ato open . --watch
ato open . -t cli
ato ps --all
ato logs --name hello-capsule --follow

Pack and Sign

Section titled “Pack and Sign”

For distribution, create a .capsule and sign with Ed25519 key. Signed artifacts can be reused in public flows or CI.

Terminal window
ato pack . --init
ato keygen --out ~/.capsule/keys/default.pem
ato sign ./dist/hello-capsule.capsule --key ~/.capsule/keys/default.pem

Next Steps

Section titled “Next Steps”

Source specs: ATO_CLI_SPEC v0.3, DRAFT_LIFECYCLE v1.2.