@capsulos/cli 0.0.0-stage → 0.1.0

package/dist/init.js

@@ -0,0 +1,106 @@
+// `capsulos init`: the one-time setup in an AWS account. Idempotent.
+//   - artifact bucket       capsulos-artifacts-<account>
+//   - build role            CapsulosBuildRole      (assumed by the image builder)
+//   - execution role        CapsulosExecutionRole  (assumed by every capsule)
+// Network connectors are deliberately not created here: they are an account
+// design decision (which VPC, which security group). Pass one with
+// --egress-connector to record it in capsulos.json.
+import { IAMClient, GetRoleCommand, CreateRoleCommand, PutRolePolicyCommand } from '@aws-sdk/client-iam';
+import { S3Client, HeadBucketCommand, CreateBucketCommand } from '@aws-sdk/client-s3';
+import { STSClient, GetCallerIdentityCommand } from '@aws-sdk/client-sts';
+import { credentialsFor, saveConfig } from './config.js';
+const BUILD_ROLE = 'CapsulosBuildRole';
+const EXEC_ROLE = 'CapsulosExecutionRole';
+const TAGS = [
+    { Key: 'Project', Value: 'capsulos' },
+    { Key: 'ManagedBy', Value: 'capsulos-cli' },
+];
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export async function init(opts) {
+    const log = opts.log ?? (() => { });
+    const credentials = credentialsFor(opts.profile);
+    const clientOpts = { region: opts.region, credentials };
+    const sts = new STSClient(clientOpts);
+    const iam = new IAMClient(clientOpts);
+    const s3 = new S3Client(clientOpts);
+    const me = await sts.send(new GetCallerIdentityCommand({}));
+    const accountId = me.Account;
+    if (!accountId)
+        throw new Error('could not resolve the AWS account id');
+    const bucket = `capsulos-artifacts-${accountId}`;
+    try {
+        await s3.send(new HeadBucketCommand({ Bucket: bucket }));
+        log(`bucket ${bucket} exists`);
+    }
+    catch {
+        await s3.send(new CreateBucketCommand({ Bucket: bucket }));
+        log(`bucket ${bucket} created`);
+    }
+    const trust = JSON.stringify({
+        Version: '2012-10-17',
+        Statement: [
+            {
+                Effect: 'Allow',
+                Principal: { Service: 'lambda.amazonaws.com' },
+                Action: ['sts:AssumeRole', 'sts:TagSession'],
+            },
+        ],
+    });
+    let created = false;
+    const ensureRole = async (name, description) => {
+        try {
+            await iam.send(new GetRoleCommand({ RoleName: name }));
+            log(`role ${name} exists`);
+        }
+        catch {
+            await iam.send(new CreateRoleCommand({ RoleName: name, AssumeRolePolicyDocument: trust, Description: description, Tags: TAGS }));
+            created = true;
+            log(`role ${name} created`);
+        }
+    };
+    await ensureRole(BUILD_ROLE, 'capsulos: assumed by the Lambda MicroVMs image builder');
+    await iam.send(new PutRolePolicyCommand({
+        RoleName: BUILD_ROLE,
+        PolicyName: 'capsulos-build',
+        PolicyDocument: JSON.stringify({
+            Version: '2012-10-17',
+            Statement: [
+                { Effect: 'Allow', Action: ['s3:GetObject'], Resource: `arn:aws:s3:::${bucket}/*` },
+                { Effect: 'Allow', Action: ['logs:CreateLogGroup', 'logs:CreateLogStream', 'logs:PutLogEvents'], Resource: 'arn:aws:logs:*:*:*' },
+            ],
+        }),
+    }));
+    await ensureRole(EXEC_ROLE, 'capsulos: assumed by every capsule (S3 mounts)');
+    const buckets = opts.s3Buckets ?? [];
+    await iam.send(new PutRolePolicyCommand({
+        RoleName: EXEC_ROLE,
+        PolicyName: 'capsulos-execution',
+        PolicyDocument: JSON.stringify({
+            Version: '2012-10-17',
+            Statement: buckets.length
+                ? [
+                    { Effect: 'Allow', Action: ['s3:ListBucket'], Resource: buckets.map((b) => `arn:aws:s3:::${b}`) },
+                    { Effect: 'Allow', Action: ['s3:GetObject', 's3:PutObject', 's3:DeleteObject'], Resource: buckets.map((b) => `arn:aws:s3:::${b}/*`) },
+                ]
+                : // IAM rejects an empty statement list; grant nothing explicitly.
+                    [{ Effect: 'Deny', Action: ['s3:*'], Resource: '*', Sid: 'NoBucketsConfiguredYet' }],
+        }),
+    }));
+    log(buckets.length ? `execution role: S3 access to ${buckets.join(', ')}` : 'execution role: no S3 buckets (pass --s3-bucket)');
+    // IAM is eventually consistent: a capsule launched right after a policy
+    // change can still be refused for a few seconds.
+    log(created ? 'roles just created: waiting 10s for IAM to propagate' : 'policies updated: waiting 10s for IAM to propagate');
+    await sleep(10_000);
+    const cfg = {
+        region: opts.region,
+        accountId,
+        bucket,
+        buildRoleArn: `arn:aws:iam::${accountId}:role/${BUILD_ROLE}`,
+        executionRoleArn: `arn:aws:iam::${accountId}:role/${EXEC_ROLE}`,
+        ...(opts.egressConnectorArn ? { egressConnectorArn: opts.egressConnectorArn } : {}),
+    };
+    const path = saveConfig(cfg);
+    log(`wrote ${path}`);
+    return cfg;
+}
+//# sourceMappingURL=init.js.map

package/dist/init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"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"}

package/dist/shell.d.ts

@@ -0,0 +1,2 @@
+import { type Provider } from '@capsulos/sdk';
+export declare function shell(provider: Provider, id: string, cmd?: string): Promise<number>;

package/dist/shell.js

@@ -0,0 +1,31 @@
+// `capsulos shell <id>`: your terminal, attached to a capsule's pty. Raw mode
+// so that every key (ctrl-c, arrows, tab) goes to the capsule; the session
+// ends when the remote shell exits.
+import { Capsule } from '@capsulos/sdk';
+export async function shell(provider, id, cmd) {
+    const capsule = await Capsule.connect(provider, id);
+    const { stdin, stdout } = process;
+    const size = () => ({ cols: stdout.columns || 80, rows: stdout.rows || 24 });
+    const term = await capsule.pty.open({ cmd, ...size(), onData: (chunk) => stdout.write(chunk) });
+    const onKey = (data) => term.write(new Uint8Array(data));
+    const onResize = () => {
+        const s = size();
+        term.resize(s.cols, s.rows);
+    };
+    if (stdin.isTTY)
+        stdin.setRawMode(true);
+    stdin.resume();
+    stdin.on('data', onKey);
+    stdout.on('resize', onResize);
+    try {
+        return await term.wait();
+    }
+    finally {
+        stdin.off('data', onKey);
+        stdout.off('resize', onResize);
+        if (stdin.isTTY)
+            stdin.setRawMode(false);
+        stdin.pause();
+    }
+}
+//# sourceMappingURL=shell.js.map

package/dist/shell.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell.js","sourceRoot":"","sources":["../src/shell.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,2EAA2E;AAC3E,oCAAoC;AACpC,OAAO,EAAE,OAAO,EAAiB,MAAM,eAAe,CAAC;AAEvD,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,QAAkB,EAAE,EAAU,EAAE,GAAY;IACtE,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IACpD,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IAClC,MAAM,IAAI,GAAG,GAAG,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,OAAO,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,IAAI,EAAE,EAAE,CAAC,CAAC;IAC7E,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,EAAE,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAEhG,MAAM,KAAK,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;IACjE,MAAM,QAAQ,GAAG,GAAG,EAAE;QACpB,MAAM,CAAC,GAAG,IAAI,EAAE,CAAC;QACjB,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC,CAAC;IACF,IAAI,KAAK,CAAC,KAAK;QAAE,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;IACxC,KAAK,CAAC,MAAM,EAAE,CAAC;IACf,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACxB,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC9B,IAAI,CAAC;QACH,OAAO,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;IAC3B,CAAC;YAAS,CAAC;QACT,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QACzB,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;QAC/B,IAAI,KAAK,CAAC,KAAK;YAAE,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;QACzC,KAAK,CAAC,KAAK,EAAE,CAAC;IAChB,CAAC;AACH,CAAC"}

package/dist/template.d.ts

@@ -0,0 +1,24 @@
+import { type CapsulosConfig } from './config.js';
+export interface TemplateBuildOptions {
+    name: string;
+    /** Directory with the Dockerfile (and anything it COPYs). */
+    context: string;
+    dockerfile?: string;
+    /** Prebuilt linux/arm64 capsulod; when omitted, built from --daemon-src with Go. */
+    capsulod?: string;
+    /** Path to the daemon's Go module (defaults to the monorepo's daemon/). */
+    daemonSrc?: string;
+    memoryMiB?: number;
+    profile?: string;
+    description?: string;
+    log?: (msg: string) => void;
+}
+export declare function imageArn(cfg: CapsulosConfig, name: string): string;
+/** Resolve or cross-compile capsulod for linux/arm64 (the service runs Graviton). */
+export declare function resolveCapsulod(opts: Pick<TemplateBuildOptions, 'capsulod' | 'daemonSrc' | 'log'>): string;
+/** Build the zip the image builder consumes: context + Dockerfile + capsulod at the root. */
+export declare function assembleArtifact(opts: TemplateBuildOptions, capsulod: string): Buffer;
+export declare function templateBuild(cfg: CapsulosConfig, opts: TemplateBuildOptions): Promise<{
+    imageArn: string;
+    version: string;
+}>;

package/dist/template.js

@@ -0,0 +1,120 @@
+// `capsulos template build <name>`: a Dockerfile becomes a MicrovmImage.
+//   1. assemble a build context: the user's directory + Dockerfile + capsulod
+//   2. zip it and upload to the artifact bucket
+//   3. CreateMicrovmImage (or UpdateMicrovmImage → new version) with
+//      additionalOsCapabilities=ALL (mounts) and the /ready + /run hooks
+//   4. poll until CREATED/UPDATED
+// The Dockerfile must end up running capsulod on :8080 (see templates/base).
+import { execFileSync } from 'node:child_process';
+import { cpSync, existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
+import { LambdaMicrovmsClient, CreateMicrovmImageCommand, UpdateMicrovmImageCommand, GetMicrovmImageCommand, } from '@aws-sdk/client-lambda-microvms';
+import { credentialsFor } from './config.js';
+const HOOKS_PORT = 9000;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export function imageArn(cfg, name) {
+    return `arn:aws:lambda:${cfg.region}:${cfg.accountId}:microvm-image:${name}`;
+}
+/** Resolve or cross-compile capsulod for linux/arm64 (the service runs Graviton). */
+export function resolveCapsulod(opts) {
+    if (opts.capsulod) {
+        if (!existsSync(opts.capsulod))
+            throw new Error(`capsulod binary not found: ${opts.capsulod}`);
+        return resolve(opts.capsulod);
+    }
+    const here = dirname(fileURLToPath(import.meta.url));
+    const src = opts.daemonSrc ?? resolve(here, '..', '..', '..', 'daemon');
+    if (!existsSync(join(src, 'go.mod'))) {
+        throw new Error(`no capsulod binary given and no daemon source at ${src}; pass --capsulod <path> (download capsulod-linux-arm64 from https://github.com/tornoai/capsulos/releases) or --daemon-src <dir>`);
+    }
+    const out = join(mkdtempSync(join(tmpdir(), 'capsulod-')), 'capsulod');
+    opts.log?.(`building capsulod for linux/arm64 from ${src}`);
+    execFileSync('go', ['build', '-trimpath', '-ldflags', '-s -w', '-o', out, './cmd/capsulod'], {
+        cwd: src,
+        env: { ...process.env, CGO_ENABLED: '0', GOOS: 'linux', GOARCH: 'arm64' },
+        stdio: 'inherit',
+    });
+    return out;
+}
+/** Build the zip the image builder consumes: context + Dockerfile + capsulod at the root. */
+export function assembleArtifact(opts, capsulod) {
+    const context = resolve(opts.context);
+    const dockerfile = resolve(opts.dockerfile ?? join(context, 'Dockerfile'));
+    if (!existsSync(dockerfile))
+        throw new Error(`Dockerfile not found: ${dockerfile}`);
+    const stage = mkdtempSync(join(tmpdir(), 'capsulos-template-'));
+    try {
+        cpSync(context, stage, { recursive: true });
+        cpSync(dockerfile, join(stage, 'Dockerfile'));
+        cpSync(capsulod, join(stage, 'capsulod'));
+        const zipPath = join(stage, '..', `capsulos-${opts.name}.zip`);
+        rmSync(zipPath, { force: true });
+        execFileSync('zip', ['-q', '-r', '-X', zipPath, '.'], { cwd: stage });
+        return readFileSync(zipPath);
+    }
+    finally {
+        rmSync(stage, { recursive: true, force: true });
+    }
+}
+export async function templateBuild(cfg, opts) {
+    const log = opts.log ?? (() => { });
+    const credentials = credentialsFor(opts.profile);
+    const s3 = new S3Client({ region: cfg.region, credentials });
+    const mvm = new LambdaMicrovmsClient({ region: cfg.region, credentials });
+    const capsulod = resolveCapsulod(opts);
+    const zip = assembleArtifact(opts, capsulod);
+    const key = `templates/${opts.name}.zip`;
+    await s3.send(new PutObjectCommand({ Bucket: cfg.bucket, Key: key, Body: zip }));
+    log(`uploaded s3://${cfg.bucket}/${key} (${zip.length} bytes)`);
+    const arn = imageArn(cfg, opts.name);
+    const spec = {
+        codeArtifact: { uri: `s3://${cfg.bucket}/${key}` },
+        baseImageArn: `arn:aws:lambda:${cfg.region}:aws:microvm-image:al2023-1`,
+        buildRoleArn: cfg.buildRoleArn,
+        cpuConfigurations: [{ architecture: 'ARM_64' }],
+        resources: [{ minimumMemoryInMiB: opts.memoryMiB ?? 512 }],
+        // Verified: without this the capsule has Docker's capability set and
+        // cannot mount anything (docs/lambda-microvms-findings.md).
+        additionalOsCapabilities: ['ALL'],
+        hooks: {
+            port: HOOKS_PORT,
+            microvmHooks: { run: 'ENABLED', runTimeoutInSeconds: 60 },
+            microvmImageHooks: { ready: 'ENABLED', readyTimeoutInSeconds: 120 },
+        },
+    };
+    const t0 = Date.now();
+    try {
+        await mvm.send(new CreateMicrovmImageCommand({
+            name: opts.name,
+            description: opts.description ?? `capsulos template ${opts.name}`,
+            tags: { project: 'capsulos' },
+            ...spec,
+        }));
+        log(`image ${arn} created; building…`);
+    }
+    catch (err) {
+        if (err instanceof Error && err.name === 'ConflictException') {
+            await mvm.send(new UpdateMicrovmImageCommand({ imageIdentifier: arn, ...spec }));
+            log(`image ${arn} exists → new version; building…`);
+        }
+        else {
+            throw err;
+        }
+    }
+    for (;;) {
+        await sleep(10_000);
+        const img = await mvm.send(new GetMicrovmImageCommand({ imageIdentifier: arn }));
+        const elapsed = ((Date.now() - t0) / 1000).toFixed(0);
+        log(`state=${img.state} (t+${elapsed}s)`);
+        if (img.state === 'CREATED' || img.state === 'UPDATED') {
+            return { imageArn: arn, version: String(img.latestActiveImageVersion ?? '') };
+        }
+        if (img.state?.endsWith('_FAILED')) {
+            throw new Error(`build failed: ${img.state} — see CloudWatch /aws/lambda-microvms/${opts.name}`);
+        }
+    }
+}
+//# sourceMappingURL=template.js.map

package/dist/template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.js","sourceRoot":"","sources":["../src/template.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,71 @@
 {
   "name": "@capsulos/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "capsulos command line: set up your AWS account, build templates, list and kill capsules.",
+  "license": "Apache-2.0",
+  "keywords": [
+    "sandbox",
+    "ai-agents",
+    "aws",
+    "lambda",
+    "microvm",
+    "firecracker",
+    "e2b",
+    "daytona"
+  ],
+  "homepage": "https://github.com/tornoai/capsulos#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tornoai/capsulos.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/tornoai/capsulos/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "type": "module",
+  "bin": {
+    "capsulos": "./bin/capsulos.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "files": [
+    "bin",
+    "dist",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@aws-sdk/client-iam": "^3.1158.0",
+    "@aws-sdk/client-lambda-microvms": "^3.1158.0",
+    "@aws-sdk/client-s3": "^3.1158.0",
+    "@aws-sdk/client-sts": "^3.1158.0",
+    "@aws-sdk/credential-providers": "^3.1158.0",
+    "@capsulos/provider-docker": "0.1.0",
+    "@capsulos/provider-lambda": "0.1.0",
+    "@capsulos/sdk": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.1",
+    "tsx": "^4.23.1",
+    "typescript": "^5.9.0",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run --passWithNoTests",
+    "dev": "tsx src/cli.ts"
+  }
 }

package/src/cli.ts

@@ -0,0 +1,162 @@
+// capsulos <command>
+//   init            set up the AWS account (bucket + roles) → capsulos.json
+//   template build  Dockerfile → MicrovmImage
+//   run <template>  create a capsule, print its id
+//   ls <template>   capsules of a template
+//   shell <id>      attach your terminal to a capsule
+//   forward <id> <port>  http://localhost:<port> → that port inside the capsule
+//   kill <id>       terminate a capsule
+// `--docker` on run/ls/shell/kill uses the local Docker provider instead of Lambda.
+import { parseArgs } from 'node:util';
+import { DockerProvider } from '@capsulos/provider-docker';
+import { LambdaProvider } from '@capsulos/provider-lambda';
+import { Capsule, type Provider } from '@capsulos/sdk';
+import { credentialsFor, loadConfig } from './config.js';
+import { forward } from './forward.js';
+import { init } from './init.js';
+import { shell } from './shell.js';
+import { templateBuild } from './template.js';
+
+const log = (msg: string) => console.error(`[capsulos] ${msg}`);
+
+function usage(): never {
+  console.error(`usage:
+  capsulos init [--region us-east-1] [--profile p] [--s3-bucket b ...] [--egress-connector arn]
+  capsulos template build <name> --context <dir> [--dockerfile f] [--capsulod bin | --daemon-src dir] [--memory 512] [--profile p]
+  capsulos run <template> [--docker | --profile p]
+  capsulos ls <template> [--docker | --profile p]
+  capsulos shell <id> [--cmd /bin/bash] [--docker | --profile p]
+  capsulos forward <id> <port> [--local-port p] [--docker | --profile p]
+  capsulos kill <id> [--docker | --profile p]`);
+  process.exit(2);
+}
+
+const providerFlags = { profile: { type: 'string' }, docker: { type: 'boolean', default: false } } as const;
+
+function provider(opts: { profile?: string; docker?: boolean }): Provider {
+  if (opts.docker) return new DockerProvider();
+  return lambdaProvider(opts.profile);
+}
+
+function lambdaProvider(profile?: string): LambdaProvider {
+  const cfg = loadConfig();
+  return new LambdaProvider({
+    region: cfg.region,
+    accountId: cfg.accountId,
+    credentials: credentialsFor(profile),
+    executionRoleArn: cfg.executionRoleArn,
+    ...(cfg.egressConnectorArn ? { egressConnectorArn: cfg.egressConnectorArn } : {}),
+  });
+}
+
+export async function main(argv = process.argv.slice(2)): Promise<void> {
+  const [cmd, ...rest] = argv;
+  switch (cmd) {
+    case 'init': {
+      const { values } = parseArgs({
+        args: rest,
+        options: {
+          region: { type: 'string', default: process.env.AWS_REGION ?? 'us-east-1' },
+          profile: { type: 'string' },
+          's3-bucket': { type: 'string', multiple: true },
+          'egress-connector': { type: 'string' },
+        },
+      });
+      const cfg = await init({
+        region: values.region!,
+        profile: values.profile,
+        s3Buckets: values['s3-bucket'],
+        egressConnectorArn: values['egress-connector'],
+        log,
+      });
+      console.log(JSON.stringify(cfg, null, 2));
+      return;
+    }
+    case 'template': {
+      const [sub, name, ...args] = rest;
+      if (sub !== 'build' || !name) usage();
+      const { values } = parseArgs({
+        args,
+        options: {
+          context: { type: 'string' },
+          dockerfile: { type: 'string' },
+          capsulod: { type: 'string' },
+          'daemon-src': { type: 'string' },
+          memory: { type: 'string' },
+          profile: { type: 'string' },
+          description: { type: 'string' },
+        },
+      });
+      if (!values.context) usage();
+      const res = await templateBuild(loadConfig(), {
+        name,
+        context: values.context,
+        dockerfile: values.dockerfile,
+        capsulod: values.capsulod,
+        daemonSrc: values['daemon-src'],
+        memoryMiB: values.memory ? Number(values.memory) : undefined,
+        profile: values.profile,
+        description: values.description,
+        log,
+      });
+      console.log(JSON.stringify(res, null, 2));
+      return;
+    }
+    case 'run': {
+      const [template, ...args] = rest;
+      if (!template) usage();
+      const { values } = parseArgs({ args, options: providerFlags });
+      const t0 = Date.now();
+      const capsule = await Capsule.create(provider(values), {
+        template,
+        idle: { suspendAfterSeconds: 600, destroyAfterSeconds: 4 * 3600 },
+      });
+      log(`capsule ready in ${Date.now() - t0}ms`);
+      console.log(capsule.id);
+      return;
+    }
+    case 'ls': {
+      const [template, ...args] = rest;
+      if (!template) usage();
+      const { values } = parseArgs({ args, options: providerFlags });
+      const list = await provider(values).list(template);
+      for (const c of list) console.log(`${c.id}\t${c.state}\t${c.createdAt?.toISOString() ?? ''}`);
+      return;
+    }
+    case 'shell': {
+      const [id, ...args] = rest;
+      if (!id) usage();
+      const { values } = parseArgs({ args, options: { ...providerFlags, cmd: { type: 'string' } } });
+      const code = await shell(provider(values), id, values.cmd);
+      process.exit(code);
+    }
+    case 'forward': {
+      const [id, portStr, ...args] = rest;
+      const port = Number(portStr);
+      if (!id || !Number.isInteger(port) || port < 1) usage();
+      const { values } = parseArgs({ args, options: { ...providerFlags, 'local-port': { type: 'string' } } });
+      const { url } = await forward(provider(values), id, port, {
+        localPort: values['local-port'] ? Number(values['local-port']) : undefined,
+        log,
+      });
+      console.log(url);
+      await new Promise<void>((resolve) => process.once('SIGINT', resolve));
+      return;
+    }
+    case 'kill': {
+      const [id, ...args] = rest;
+      if (!id) usage();
+      const { values } = parseArgs({ args, options: providerFlags });
+      await provider(values).terminate(id);
+      log(`terminated ${id}`);
+      return;
+    }
+    default:
+      usage();
+  }
+}
+
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : err);
+  process.exit(1);
+});

package/src/config.ts

@@ -0,0 +1,47 @@
+// capsulos.json: what `capsulos init` created in the AWS account, read by
+// every other command and by the examples. Lives in the project directory.
+import { readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fromNodeProviderChain } from '@aws-sdk/credential-providers';
+import type { LambdaMicrovmsClientConfig } from '@aws-sdk/client-lambda-microvms';
+
+export type Credentials = NonNullable<LambdaMicrovmsClientConfig['credentials']>;
+
+export interface CapsulosConfig {
+  region: string;
+  accountId: string;
+  /** Artifact bucket for template zips. */
+  bucket: string;
+  /** Role the image builder assumes (reads the zip, writes build logs). */
+  buildRoleArn: string;
+  /** Role every capsule assumes (S3 mounts and whatever else you grant). */
+  executionRoleArn: string;
+  /** Optional egress connector (e.g. a VPC connector with a deny-all security group). */
+  egressConnectorArn?: string;
+}
+
+export const CONFIG_FILE = 'capsulos.json';
+
+export function configPath(cwd = process.cwd()): string {
+  return resolve(cwd, CONFIG_FILE);
+}
+
+export function loadConfig(cwd = process.cwd()): CapsulosConfig {
+  try {
+    return JSON.parse(readFileSync(configPath(cwd), 'utf8')) as CapsulosConfig;
+  } catch {
+    throw new Error(`${CONFIG_FILE} not found in ${cwd}. Run \`capsulos init\` first.`);
+  }
+}
+
+export function saveConfig(cfg: CapsulosConfig, cwd = process.cwd()): string {
+  const p = configPath(cwd);
+  writeFileSync(p, `${JSON.stringify(cfg, null, 2)}\n`);
+  return p;
+}
+
+/** Env vars first (`aws configure export-credentials`), then the profile. */
+export function credentialsFor(profile?: string): Credentials {
+  if (process.env.AWS_ACCESS_KEY_ID || !profile) return fromNodeProviderChain();
+  return fromNodeProviderChain({ profile });
+}