oo env
Create machines for a task, run commands and move files.
Create and use Linux or macOS machines from Namespace, for your task or an agent's. environments.create lets you create or extend directly. Administrator-set allowances only cap concurrent machines and spending; managed machines reserve the team balance first. On-demand machines stop after 15 minutes idle; without retained storage, this deletes them. --keep-until-deadline disables idle stopping. Runs, files, the terminal, ports and desktop never start a stopped machine. Captured run output stays readable for 30 days.
oo env profiles
List the profiles you may create from, and, with environments.manage, add, revise and archive them. A profile is a machine spec on a connection; oo api route POST /api/v1/environment-profiles shows its fields. A revision never changes a machine already created from an earlier one.
oo env profiles [COMMAND]It also takes the connection options.
oo env profiles list
List the profiles you may create from
oo env profiles listIt also takes the connection options.
oo env profiles create
Add a profile from a JSON file
oo env profiles create [options]| Argument | Required | Default | Choices | Description |
|---|---|---|---|---|
--file FILE | yes | the profile: name, connectionId, spec and visibility, as a JSON object; - reads stdin |
It also takes the connection options.
oo env profiles revise
Give a profile a new revision from a JSON file
oo env profiles revise [options] PROFILE_ID| Argument | Required | Default | Choices | Description |
|---|---|---|---|---|
PROFILE_ID | yes | profile ID from oo env profiles list | ||
--file FILE | yes | the new spec, and a new name if any, as a JSON object; - reads stdin |
It also takes the connection options.
oo env profiles archive
Archive a profile; nobody creates from it again
oo env profiles archive [options] PROFILE_ID| Argument | Required | Default | Choices | Description |
|---|---|---|---|---|
PROFILE_ID | yes | profile ID from oo env profiles list | ||
--yes | no | confirm it now; an agent passes it only once the person confirmed it in chat |
It also takes the connection options.
oo env list
List the environments you may see
oo env listIt also takes the connection options.
oo env get
Show one environment's state
oo env get [options] ENV_ID| Argument | Required | Default | Choices | Description |
|---|---|---|---|---|
ENV_ID | yes | environment ID from oo env list | ||
--wait SECONDS | no | wait up to this long, 1 to 30, for its next change |
It also takes the connection options.
oo env rename
Give a machine the name people see for it here, as Rename on its page does. Its ID and purpose stay. Its owner, or whoever holds environments.manage on it, renames it, with environments.use on it.
oo env rename ENV_ID NAME| Argument | Required | Default | Choices | Description |
|---|---|---|---|---|
ENV_ID | yes | environment ID from oo env list | ||
NAME | yes | what to call it: one line of at most 80 characters |
It also takes the connection options.
oo env create
Create a machine from a profile
oo env create [options]| Argument | Required | Default | Choices | Description |
|---|---|---|---|---|
--profile PROFILE_ID | yes | profile ID from oo env profiles list | ||
--duration DURATION | no | 1800 | maximum lifetime, such as 30m or 2h (default 30m) | |
--purpose PURPOSE | no | what the machine is for | ||
--keep-until-deadline | no | keep compute running even while idle | ||
--retain-until TIME | no | keep a persistent profile's disk until this date (ISO 8601) |
It also takes the connection options.
oo env start
Start before the deadline
oo env start ENV_ID| Argument | Required | Default | Choices | Description |
|---|---|---|---|---|
ENV_ID | yes | environment ID from oo env list |
It also takes the connection options.
oo env stop
Stop compute; retained storage follows its retention policy
oo env stop [options] ENV_ID| Argument | Required | Default | Choices | Description |
|---|---|---|---|---|
ENV_ID | yes | environment ID from oo env list | ||
--yes | no | confirm it now; an agent passes it only once the person confirmed it in chat |
It also takes the connection options.
oo env delete
Delete the machine with everything on it
oo env delete [options] ENV_ID| Argument | Required | Default | Choices | Description |
|---|---|---|---|---|
ENV_ID | yes | environment ID from oo env list | ||
--yes | no | confirm it now; an agent passes it only once the person confirmed it in chat |
It also takes the connection options.
oo env extend
Extend a machine's deadline directly
oo env extend [options] ENV_ID| Argument | Required | Default | Choices | Description |
|---|---|---|---|---|
ENV_ID | yes | environment ID from oo env list | ||
--deadline TIME | yes | the new deadline, in UTC (ISO 8601) |
It also takes the connection options.
oo env resolve-cleanup
Resolve a deleted environment's cleanup by hand, as Resolve cleanup on its page does: when Namespace no longer has the machine on your own Namespace account but can't confirm its snapshots, an administrator who checked them in Namespace confirms they are gone, and --evidence, what they checked, goes into the audit log. It needs environments.manage on the environment. Only such a cleanup can be resolved (cleanup_resolution_unavailable), not while Namespace still has the machine (machine_still_exists), and never a managed machine's.
oo env resolve-cleanup [options] ENV_ID| Argument | Required | Default | Choices | Description |
|---|---|---|---|---|
ENV_ID | yes | environment ID from oo env list | ||
--yes | no | confirm it now; an agent passes it only once the person confirmed it in chat | ||
--evidence TEXT | yes | what you checked, at most 1000 characters; kept in the audit log |
It also takes the connection options.
oo env restore
Restore a stopped BYO machine from a snapshot
oo env restore [options] ENV_ID SNAPSHOT_ID| Argument | Required | Default | Choices | Description |
|---|---|---|---|---|
ENV_ID | yes | environment ID from oo env list | ||
SNAPSHOT_ID | yes | the restore point, from oo env snapshots list | ||
--yes | no | confirm it now; an agent passes it only once the person confirmed it in chat |
It also takes the connection options.
oo env snapshots
A BYO machine's restore points
oo env snapshots [COMMAND]It also takes the connection options.
oo env snapshots list
List restore points
oo env snapshots list ENV_ID| Argument | Required | Default | Choices | Description |
|---|---|---|---|---|
ENV_ID | yes | environment ID from oo env list |
It also takes the connection options.
oo env clone
Create a copy of a BYO machine from a snapshot
oo env clone [options] ENV_ID| Argument | Required | Default | Choices | Description |
|---|---|---|---|---|
ENV_ID | yes | environment ID from oo env list | ||
--snapshot SNAPSHOT_ID | yes | the restore point to copy, from oo env snapshots list | ||
--duration DURATION | no | 1800 | maximum lifetime, such as 30m or 2h (default 30m) | |
--purpose PURPOSE | no | what the machine is for | ||
--keep-until-deadline | no | keep compute running even while idle | ||
--retain-until TIME | no | keep a persistent profile's disk until this date (ISO 8601) |
It also takes the connection options.
oo env lease
Take a BYO machine from a pool or give it back
oo env lease [COMMAND]It also takes the connection options.
oo env lease acquire
Take a machine from a pooled profile
oo env lease acquire [options]| Argument | Required | Default | Choices | Description |
|---|---|---|---|---|
--profile PROFILE_ID | yes | |||
--duration DURATION | no | 1800 | maximum lifetime, such as 30m or 2h (default 30m) | |
--purpose PURPOSE | no | what the machine is for | ||
--keep-until-deadline | no | keep compute running even while idle | ||
--retain-until TIME | no | keep a persistent profile's disk until this date (ISO 8601) |
It also takes the connection options.
oo env lease release
Return a machine to its pool
oo env lease release [options] ENV_ID| Argument | Required | Default | Choices | Description |
|---|---|---|---|---|
ENV_ID | yes | environment ID from oo env list | ||
--yes | no | confirm it now; an agent passes it only once the person confirmed it in chat |
It also takes the connection options.
oo env allowances
Set caps per member or agent. Without an allowance there is no extra cap.
oo env allowances [COMMAND]It also takes the connection options.
oo env allowances list
List caps and their current use (admin)
oo env allowances listIt also takes the connection options.
oo env allowances set
Set caps for one member or agent (admin)
oo env allowances set [options]| Argument | Required | Default | Choices | Description |
|---|---|---|---|---|
--principal user:ID|agent:ID | yes | the member or agent the caps apply to | ||
--max-concurrent COUNT | no | most machines at once | ||
--max-spend USD | no | maximum spend in USD over --window-days | ||
--window-days DAYS | no | the spending window, 1 to 30 days |
It also takes the connection options.
oo env allowances revoke
Remove an allowance's caps (admin)
oo env allowances revoke [options] ALLOWANCE_ID| Argument | Required | Default | Choices | Description |
|---|---|---|---|---|
ALLOWANCE_ID | yes | the allowance, from oo env allowances list | ||
--yes | no | confirm it now; an agent passes it only once the person confirmed it in chat |
It also takes the connection options.
oo env run
Run a program in a running environment and wait for its end. oo prints the run, with its status and exit code, and what it wrote to stdout and stderr, and exits with the program's exit code, or 1 when it did not exit by itself: cancelled, timed out, lost or never started. --detach prints the run at once instead; follow it with oo env runs. An interrupted wait never cancels the run.
oo env run [options] ENV_ID [argv ...]| Argument | Required | Default | Choices | Description |
|---|---|---|---|---|
ENV_ID | yes | environment ID from oo env list | ||
--cwd DIR | no | working directory (default the home directory) | ||
--env NAME=VALUE | no | an environment variable for the program; repeatable; values are never stored | ||
--output PATH | no | a file the program makes, kept with its sha256 when the run ends; absolute or relative to --cwd; repeatable | ||
--detach | no | print the started run without waiting for its end | ||
--deadline SECONDS | no | cancel the run after this long (default 3600) | ||
--idempotency-key KEY | no | names the run: repeating the key returns that run instead of starting another | ||
argv | no | the program and its arguments, after -- |
It also takes the connection options.
oo env runs
List runs, read their output, cancel them
oo env runs [COMMAND]It also takes the connection options.
oo env runs list
List an environment's runs, newest first
oo env runs list ENV_ID| Argument | Required | Default | Choices | Description |
|---|---|---|---|---|
ENV_ID | yes | environment ID from oo env list |
It also takes the connection options.
oo env runs get
Show a run with its status, exit code and what it kept
oo env runs get RUN_ID| Argument | Required | Default | Choices | Description |
|---|---|---|---|---|
RUN_ID | yes | run ID from oo env run or oo env runs list |
It also takes the connection options.
oo env runs logs
Print what a run wrote to one stream from --from-offset, as JSON with the data and its nextOffset: read again from there for more. --follow prints each new part until the run ends. Once the run ended, its output is read from what the Sunport kept.
oo env runs logs [options] RUN_ID| Argument | Required | Default | Choices | Description |
|---|---|---|---|---|
RUN_ID | yes | run ID from oo env run or oo env runs list | ||
--stream STREAM | no | stdout | stdout, stderr | |
--from-offset BYTES | no | 0 | the byte to start from (default 0) | |
--follow | no | keep printing new output until the run ends |
It also takes the connection options.
oo env runs wait
Follow a run until it ends and print it. oo exits with the program's exit code, or 1 when it did not exit by itself; stopping the wait never cancels the run.
oo env runs wait RUN_ID| Argument | Required | Default | Choices | Description |
|---|---|---|---|---|
RUN_ID | yes | run ID from oo env run or oo env runs list |
It also takes the connection options.
oo env runs cancel
Stop a run and every process it started
oo env runs cancel [options] RUN_ID| Argument | Required | Default | Choices | Description |
|---|---|---|---|---|
RUN_ID | yes | run ID from oo env run or oo env runs list | ||
--yes | no | confirm it now; an agent passes it only once the person confirmed it in chat |
It also takes the connection options.
oo env files
List a directory on a running environment
oo env files [COMMAND]It also takes the connection options.
oo env files ls
List a directory
oo env files ls ENV_ID path| Argument | Required | Default | Choices | Description |
|---|---|---|---|---|
ENV_ID | yes | environment ID from oo env list | ||
path | yes | the directory's path on the machine |
It also takes the connection options.
oo env cp
Copy one file between this computer and a running environment, where ENV_ID:PATH names the file on the machine. A download goes into a new protected file (--overwrite replaces one), in 8 MiB parts. An upload sends a file of up to 8 MiB with its mode and replaces a file there; a PATH ending in / keeps the local name.
oo env cp [options] source destination| Argument | Required | Default | Choices | Description |
|---|---|---|---|---|
source | yes | a local file, or ENV_ID:PATH on the machine | ||
destination | yes | ENV_ID:PATH on the machine, or a local file or directory | ||
--overwrite | no | replace an existing local file |
It also takes the connection options.
oo env artifacts
List and download what a run kept when it ended: 0 is its stdout, 1 its stderr, then each file it named with --output, in order. Each stays for 30 days, with its size and sha256.
oo env artifacts [COMMAND]It also takes the connection options.
oo env artifacts list
List what a run kept, by index
oo env artifacts list RUN_ID| Argument | Required | Default | Choices | Description |
|---|---|---|---|---|
RUN_ID | yes | run ID from oo env run or oo env runs list |
It also takes the connection options.
oo env artifacts get
Download one item a run kept, by its index. The download is kept only if its size and sha256 match what the Sunport recorded.
oo env artifacts get [options] RUN_ID index [local]| Argument | Required | Default | Choices | Description |
|---|---|---|---|---|
RUN_ID | yes | run ID from oo env run or oo env runs list | ||
index | yes | the item's index, from oo env artifacts list | ||
local | no | where to save it (default the kept file's name, or RUN_ID.stdout or RUN_ID.stderr, here) | ||
--overwrite | no | replace an existing local file |
It also takes the connection options.
oo env desktop
See and work the screen of a running macOS environment: save a screenshot, click at screen pixel coordinates from the top left, type text as on a US keyboard, and press keys. A screenshot may be smaller than the screen: its scale says by how much, and a point on it times the scale is the point to click. Linux environments have no desktop.
oo env desktop [COMMAND]It also takes the connection options.
oo env desktop screenshot
Save the screen as an image
oo env desktop screenshot [options] ENV_ID [local]| Argument | Required | Default | Choices | Description |
|---|---|---|---|---|
ENV_ID | yes | environment ID from oo env list | ||
local | no | where to save it (default ENV_ID.jpg, or ENV_ID.png with --format png) | ||
--overwrite | no | replace an existing local file | ||
--format FORMAT | no | jpeg | jpeg, png | png keeps every pixel (default jpeg) |
--max-width PIXELS | no | 1280 | shrink the screen by a whole factor to at most this width (default 1280) |
It also takes the connection options.
oo env desktop click
Click at a point of the screen
oo env desktop click [options] ENV_ID x y| Argument | Required | Default | Choices | Description |
|---|---|---|---|---|
ENV_ID | yes | environment ID from oo env list | ||
x | yes | pixels from the left | ||
y | yes | pixels from the top | ||
--button BUTTON | no | left | left, middle, right | |
--double | no | double-click, as to open a file or an app |
It also takes the connection options.
oo env desktop type
Type text into the focused window
oo env desktop type ENV_ID text| Argument | Required | Default | Choices | Description |
|---|---|---|---|---|
ENV_ID | yes | environment ID from oo env list | ||
text | yes | the text; a newline presses Return |
It also takes the connection options.
oo env desktop key
Press a key or combination
oo env desktop key ENV_ID KEYS| Argument | Required | Default | Choices | Description |
|---|---|---|---|---|
ENV_ID | yes | environment ID from oo env list | ||
KEYS | yes | such as Return, Escape, cmd+s or ctrl+shift+t |
It also takes the connection options.
oo env ports
List, open and close the ports of an environment that previews may reach. Closing a port also ends its previews.
oo env ports [COMMAND]It also takes the connection options.
oo env ports list
List the open ports
oo env ports list ENV_ID| Argument | Required | Default | Choices | Description |
|---|---|---|---|---|
ENV_ID | yes | environment ID from oo env list |
It also takes the connection options.
oo env ports open
Open a port for previews
oo env ports open ENV_ID port| Argument | Required | Default | Choices | Description |
|---|---|---|---|---|
ENV_ID | yes | environment ID from oo env list | ||
port | yes | the port on the machine, 1 to 65535 |
It also takes the connection options.
oo env ports close
Close a port and end its previews
oo env ports close [options] ENV_ID port| Argument | Required | Default | Choices | Description |
|---|---|---|---|---|
ENV_ID | yes | environment ID from oo env list | ||
port | yes | the port on the machine, 1 to 65535 | ||
--yes | no | confirm it now; an agent passes it only once the person confirmed it in chat |
It also takes the connection options.
oo env preview
Print a link to an open port's preview, on the Sunport's preview domain. It works once, within a minute; open it in your browser.
oo env preview ENV_ID port| Argument | Required | Default | Choices | Description |
|---|---|---|---|---|
ENV_ID | yes | environment ID from oo env list | ||
port | yes | the port on the machine, 1 to 65535 |
It also takes the connection options.
oo env shell
Open a terminal on a running environment, in this terminal: keys go to the machine as typed and its size follows this window. It ends when the machine's shell exits, the environment stops or reaches its deadline, or your access ends; oo then exits 0 if the session ended normally, 1 otherwise.
oo env shell ENV_ID| Argument | Required | Default | Choices | Description |
|---|---|---|---|---|
ENV_ID | yes | environment ID from oo env list |
It also takes the connection options.
oo env port-forward
Listen on LOCAL on this computer (127.0.0.1 only) and carry each connection to REMOTE on the machine, through the Sunport. It prints the address it listens on and runs until interrupted; 0 as LOCAL picks a free port.
oo env port-forward ENV_ID LOCAL:REMOTE| Argument | Required | Default | Choices | Description |
|---|---|---|---|---|
ENV_ID | yes | environment ID from oo env list | ||
LOCAL:REMOTE | yes | the local and the machine's port, or one port for both |
It also takes the connection options.
oo env ssh-config
Print a Host block for your SSH config. Its ProxyCommand runs this oo, which carries SSH through the Sunport's relay with your credential; the machine's own keys never leave the Sunport. Append it to ~/.ssh/config, then connect your IDE to the host named ENV_ID.
oo env ssh-config ENV_ID| Argument | Required | Default | Choices | Description |
|---|---|---|---|---|
ENV_ID | yes | environment ID from oo env list |
It also takes the connection options.
oo env ssh-proxy
Carry SSH over standard input and output (ssh-config uses it)
oo env ssh-proxy ENV_ID| Argument | Required | Default | Choices | Description |
|---|---|---|---|---|
ENV_ID | yes | environment ID from oo env list |
It also takes the connection options.