overthinkos/start

charly start -- Start Container Service

Overview

Start a container image as a background service. In quadlet mode, charly config <image> MUST be run first to generate the systemd quadlet unit. In direct mode, start creates an ephemeral container directly.

Relationship to charly bundle add — charly start <image> is the ergonomic wrapper for charly bundle add <image> <image> (container target). New scripts should prefer charly bundle add <name> <ref> directly when they need explicit deploy names, --add-candy overlays, or the host target. charly start covers the common single-image case and is retained for backwards compatibility. See /charly-core:deploy for the unified command family and /charly-local:local-deploy for the host target.

Quick Reference

| Action | Command | Description | |--------|---------|-------------| | Start (quadlet) | charly start <image> | Start via systemd quadlet unit | | Start (direct) | charly start <image> | Create ephemeral container (when run_mode=direct) | | With specific tag | charly start <image> --tag TAG | Use specific image tag | | Build first | charly start <image> --build | Build image before starting | | Named instance | charly start <image> -i INSTANCE | Start a named instance |

Direct Mode Only

| Action | Flag | Description | |--------|------|-------------| | Bind volume | --bind name=path | Override volume backing for session | | Volume config | -v name:type[:path] | Configure volume backing | | Environment | -e KEY=VALUE | Set environment variable | | Env file | --env-file PATH | Load environment from file | | Port mapping | -p PORT | Additional port mapping |

Note: -e flags use Kong sep:"none" — commas in values are preserved (e.g., NO_PROXY=localhost,127.0.0.1).

Label-Only Policy

charly start reads only OCI labels (via ExtractMetadata) + charly.yml. It does not touch charly.yml. Remote refs (@github.com/...) are rejected with a redirect to charly box pull.

If the image isn't in local storage, startup fails with the standard ErrImageNotLocal recommendation pointing to charly box pull. See /charly-build:pull.

Important: Quadlet Mode Requires Prior Configuration

In quadlet mode (default), charly config <image> MUST be run before charly start. If the quadlet file does not exist, start fails with:

not configured; run 'charly config <image>' first

The correct workflow is:

# Step 1: Configure (generates quadlet, provisions secrets, sets up volumes)
charly config sway-browser-vnc

# Step 2: Start
charly start sway-browser-vnc

Usage

Quadlet Mode (Default)

# Configure first
charly config jupyter --bind workspace --password auto

# Start the service (systemctl --user start charly-jupyter.service)
charly start jupyter

Encrypted volumes declared in the image are auto-mounted at start time. In quadlet mode, ExecStartPost commands in the quadlet file register Tailscale serve/funnel rules (if tunnel is configured in charly.yml). These are automatically cleaned up by ExecStopPost on service stop.

Quadlet auto-mount hook. Quadlets generated for encrypted-volume images carry an ExecStartPre=charly config mount <image> directive. Without it, a host reboot or any other event that drops the gocryptfs FUSE mount would let systemd start the container against an empty plain/ mountpoint — at which point the container would write plaintext data on top of the populated cipher tree. If you have quadlets generated by an older charly, run charly migrate to regenerate them in place — see /charly-build:migrate "charly migrate". Direct-mode starts have a parallel safety net: verifyBindMounts fails loud when the cipher dir is populated and the plain mount is empty (see /charly-automation:enc "Pre-start safety check").

Direct Mode

# Start with workspace and env vars
charly start jupyter -e JUPYTER_TOKEN=mytoken

# Start with port mapping
charly start jupyter -p 8888:8888

Build and Start

# Build the image first, then start
charly start jupyter --build

Cross-References

Prerequisites

• /charly-build:pull -- Required before charly start can work on a fresh host. charly start rejects remote refs (@github.com/...) — pull first.
• /charly-core:charly-config -- MUST run first in quadlet mode (setup: quadlet + secrets + encrypted volumes)

Deploy-mode neighbors

• /charly-core:service -- Full service lifecycle (in-container supervisord/systemd services)
• /charly-core:stop -- Stop a running service
• /charly-core:charly-status -- Check service status
• /charly-core:charly-update -- Update image and restart
• /charly-core:logs -- View service logs
• /charly-core:shell -- Interactive shell into the same image
• /charly-core:deploy -- Tunnel configuration (ExecStartPost commands generated by quadlet)
• /charly-automation:enc -- Encrypted volume mount lifecycle (inline mount in direct mode, ExecStartPre=charly config mount in quadlet mode, short-circuit fast path)
• /charly-build:secrets -- Credential store hierarchy for encrypted volume passphrase resolution

Build-mode references

• /charly-image:image -- Box definitions (ports, volumes, env) in charly.yml
• /charly-build:build -- Build the image you intend to start

Live-deploy verification is mandatory (see /charly-check:check 10 standards)

Changes that touch this verb's output must reach a healthy deployment on a target explicitly marked disposable: true (see /charly-internals:disposable). Use charly update <name> to destroy + rebuild unattended on any disposable target. Never experiment on a non-disposable deploy — set up a disposable one first with charly bundle add <name> <ref> --disposable or mark a VM in vm.yml.

After committing the source-level fix, charly update the disposable target ONCE MORE from clean and re-run the full verification. A fix that passes only on a hand-patched target is not a real fix — it's a regression waiting for the next unrelated rebuild. Paste BOTH the exploratory-pass output and the fresh-rebuild-pass output into the conversation.

Unit tests + a clean compile are necessary but not sufficient. See CLAUDE.md R1–R10.