codeflower run
Start a sandbox and create a new chat session with TASK as its first prompt: the request in plain words, - to read it from standard input, or –prompt FILE to read it from a Markdown file. The agent starts working immediately; connect to the worker in VS Code to follow along, answer questions, or continue the session. Unlike “task”, this command keeps the worker running for interactive follow-up.
The session is saved in the project and appears in the extension’s sessions list. If the agent is not signed in yet, the task waits until you connect and sign in.
It prints a link to open in the browser while “codeflower client” runs on your computer, which adds the sandbox there; or, in VS Code, run “code flower: Connect to worker” and paste the codeflower://… line. Press Ctrl+C to stop.
With –server the sandbox also serves its chat page on the same port and prints a link to it (http://HOST:PORT/?key=…), like Jupyter’s: open it in any browser that reaches this machine, e.g. through ssh -L. Anyone with the link controls the agent, and plain HTTP carries the key and the chats unencrypted, so keep job logs private and prefer –host 127.0.0.1 with a tunnel on shared networks.
codeflower run (TASK | --prompt FILE) [flags]Examples
Section titled “Examples” codeflower run --agent claude --input ~/data/study42 --output ~/results/study42 \ "Cluster the cells and annotate the cell types" codeflower run --agent codex --project study42 --input /data/study42 \ "Run quality control and write the filtered matrix" codeflower run --agent claude --project study42 --input /data/study42 --prompt task.md| Flag | Default | Description |
|---|---|---|
--advertise-host string |
address printed for VS Code and the page link (default: this node’s IPv4 address; 127.0.0.1 with Docker or Podman) | |
--agent string |
agent the sandbox runs: claude, codex, dsh, or opencode (or set $CODEFLOWER_AGENT; asked if left out) | |
--allowlist string |
file of hosts an isolated sandbox may reach, one per line (default: PROJECT.allowed-hosts.txt next to the project) | |
--bind stringArray |
more mounts: SOURCE[:TARGET[:ro|rw]] (repeatable; default target /data/input/NAME, read-only) | |
-c, --code stringArray |
repository or package the agent develops, mounted read-write at /data/code/NAME (repeatable) | |
--config string |
config directory with config.yaml and skills (or set $CODEFLOWER_CONFIG; default ~/.codeflower) | |
--cpus int |
CPUs the agent may use (default: the batch job’s allocation; Docker and Podman also enforce it) | |
--engine string |
auto |
container engine: auto, docker, podman, or apptainer (or set $CODEFLOWER_ENGINE) |
--host string |
0.0.0.0 |
interface the worker listens on |
--image string |
sandbox image: a Docker/Podman image name, or an Apptainer .sif file (or set $CODEFLOWER_IMAGE; default ghcr.io/lutrarutra/codeflower-sandbox:0.15.1, downloaded on first use) | |
--image-tag string |
build of the published image to use instead of 0.15.1, the release this app is made for: latest, another release (0.2.1, or 0.2 for its newest patch) or a commit (sha-abc1234) (or set $CODEFLOWER_IMAGE_TAG) | |
-i, --input stringArray |
folder with your data, mounted read-only at /data/input/NAME (repeatable) | |
--isolate-network |
cut the sandbox off the network except for its agent’s service and the hosts in the allowlist (Linux) | |
--memory string |
memory the agent may use, e.g. 32G (default: the batch job’s allocation; Docker and Podman also enforce it) | |
--no-tunnel |
keep this sandbox from browsers paired through the tunnel (it does not start the client for the tunnel either) | |
-o, --output stringArray |
folder for results, created if needed and mounted read-write at /data/output/NAME (repeatable) | |
--port int |
port of the worker (and its page with –server) (default: any free port) | |
-p, --project string |
default |
project name: its sessions, logins and workspace live in ~/codeflower/projects/NAME |
--prompt string |
read TASK from this Markdown file instead of an argument | |
--server |
also serve the chat page on the worker’s port, and print a link to open it in a browser | |
-s, --skills stringArray |
folder with a skill (a SKILL.md) or with skill folders, mounted read-only at /data/skills/NAME (repeatable) | |
--state string |
project directory, instead of –project (created with owner-only permissions) | |
--time-limit string |
time the agent has, e.g. 8h or 1-12:00:00 (default: the batch job’s time limit); reported, not enforced |