Skip to content
Publish

Getting Started

Section titled “Getting Started”

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

Prerequisites

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

Engine Setup

Section titled “Engine Setup”

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

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

Create a New Capsule

Section titled “Create a New Capsule”

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

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

Minimal capsule.toml (Lifecycle shortcut) example:

schema_version = "1.1"
name = "hello-capsule"
version = "0.1.0"
type = "app"


[lifecycle]
run = "node index.js"
port = 3000
health_check = "/health"

Validate and Run

Section titled “Validate and Run”
  1. Validate manifest - capsule validate . checks syntax/semantics/IPC conflicts.
  2. Run capsule - capsule open . executes the capsule.toml.
  3. Monitor process - capsule ps / capsule logs / capsule close for management.
Terminal window
capsule validate .
capsule open . --watch
capsule ps --all
capsule 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
capsule pack . --init
capsule keygen --out ~/.capsule/keys/default.pem
capsule sign ./dist/hello-capsule.capsule --key ~/.capsule/keys/default.pem

Next Steps

Section titled “Next Steps”

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