Skip to Content
Referenceoo CLI

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 list

It also takes the connection options.

oo env profiles create

Add a profile from a JSON file

oo env profiles create [options]
ArgumentRequiredDefaultChoicesDescription
--file FILEyesthe 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
ArgumentRequiredDefaultChoicesDescription
PROFILE_IDyesprofile ID from oo env profiles list
--file FILEyesthe 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
ArgumentRequiredDefaultChoicesDescription
PROFILE_IDyesprofile ID from oo env profiles list
--yesnoconfirm 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 list

It also takes the connection options.

oo env get

Show one environment's state

oo env get [options] ENV_ID
ArgumentRequiredDefaultChoicesDescription
ENV_IDyesenvironment ID from oo env list
--wait SECONDSnowait 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
ArgumentRequiredDefaultChoicesDescription
ENV_IDyesenvironment ID from oo env list
NAMEyeswhat 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]
ArgumentRequiredDefaultChoicesDescription
--profile PROFILE_IDyesprofile ID from oo env profiles list
--duration DURATIONno1800maximum lifetime, such as 30m or 2h (default 30m)
--purpose PURPOSEnowhat the machine is for
--keep-until-deadlinenokeep compute running even while idle
--retain-until TIMEnokeep 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
ArgumentRequiredDefaultChoicesDescription
ENV_IDyesenvironment 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
ArgumentRequiredDefaultChoicesDescription
ENV_IDyesenvironment ID from oo env list
--yesnoconfirm 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
ArgumentRequiredDefaultChoicesDescription
ENV_IDyesenvironment ID from oo env list
--yesnoconfirm 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
ArgumentRequiredDefaultChoicesDescription
ENV_IDyesenvironment ID from oo env list
--deadline TIMEyesthe 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
ArgumentRequiredDefaultChoicesDescription
ENV_IDyesenvironment ID from oo env list
--yesnoconfirm it now; an agent passes it only once the person confirmed it in chat
--evidence TEXTyeswhat 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
ArgumentRequiredDefaultChoicesDescription
ENV_IDyesenvironment ID from oo env list
SNAPSHOT_IDyesthe restore point, from oo env snapshots list
--yesnoconfirm 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
ArgumentRequiredDefaultChoicesDescription
ENV_IDyesenvironment 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
ArgumentRequiredDefaultChoicesDescription
ENV_IDyesenvironment ID from oo env list
--snapshot SNAPSHOT_IDyesthe restore point to copy, from oo env snapshots list
--duration DURATIONno1800maximum lifetime, such as 30m or 2h (default 30m)
--purpose PURPOSEnowhat the machine is for
--keep-until-deadlinenokeep compute running even while idle
--retain-until TIMEnokeep 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]
ArgumentRequiredDefaultChoicesDescription
--profile PROFILE_IDyes
--duration DURATIONno1800maximum lifetime, such as 30m or 2h (default 30m)
--purpose PURPOSEnowhat the machine is for
--keep-until-deadlinenokeep compute running even while idle
--retain-until TIMEnokeep 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
ArgumentRequiredDefaultChoicesDescription
ENV_IDyesenvironment ID from oo env list
--yesnoconfirm 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 list

It also takes the connection options.

oo env allowances set

Set caps for one member or agent (admin)

oo env allowances set [options]
ArgumentRequiredDefaultChoicesDescription
--principal user:ID|agent:IDyesthe member or agent the caps apply to
--max-concurrent COUNTnomost machines at once
--max-spend USDnomaximum spend in USD over --window-days
--window-days DAYSnothe 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
ArgumentRequiredDefaultChoicesDescription
ALLOWANCE_IDyesthe allowance, from oo env allowances list
--yesnoconfirm 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 ...]
ArgumentRequiredDefaultChoicesDescription
ENV_IDyesenvironment ID from oo env list
--cwd DIRnoworking directory (default the home directory)
--env NAME=VALUEnoan environment variable for the program; repeatable; values are never stored
--output PATHnoa file the program makes, kept with its sha256 when the run ends; absolute or relative to --cwd; repeatable
--detachnoprint the started run without waiting for its end
--deadline SECONDSnocancel the run after this long (default 3600)
--idempotency-key KEYnonames the run: repeating the key returns that run instead of starting another
argvnothe 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
ArgumentRequiredDefaultChoicesDescription
ENV_IDyesenvironment 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
ArgumentRequiredDefaultChoicesDescription
RUN_IDyesrun 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
ArgumentRequiredDefaultChoicesDescription
RUN_IDyesrun ID from oo env run or oo env runs list
--stream STREAMnostdoutstdout, stderr
--from-offset BYTESno0the byte to start from (default 0)
--follownokeep 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
ArgumentRequiredDefaultChoicesDescription
RUN_IDyesrun 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
ArgumentRequiredDefaultChoicesDescription
RUN_IDyesrun ID from oo env run or oo env runs list
--yesnoconfirm 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
ArgumentRequiredDefaultChoicesDescription
ENV_IDyesenvironment ID from oo env list
pathyesthe 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
ArgumentRequiredDefaultChoicesDescription
sourceyesa local file, or ENV_ID:PATH on the machine
destinationyesENV_ID:PATH on the machine, or a local file or directory
--overwritenoreplace 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
ArgumentRequiredDefaultChoicesDescription
RUN_IDyesrun 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]
ArgumentRequiredDefaultChoicesDescription
RUN_IDyesrun ID from oo env run or oo env runs list
indexyesthe item's index, from oo env artifacts list
localnowhere to save it (default the kept file's name, or RUN_ID.stdout or RUN_ID.stderr, here)
--overwritenoreplace 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]
ArgumentRequiredDefaultChoicesDescription
ENV_IDyesenvironment ID from oo env list
localnowhere to save it (default ENV_ID.jpg, or ENV_ID.png with --format png)
--overwritenoreplace an existing local file
--format FORMATnojpegjpeg, pngpng keeps every pixel (default jpeg)
--max-width PIXELSno1280shrink 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
ArgumentRequiredDefaultChoicesDescription
ENV_IDyesenvironment ID from oo env list
xyespixels from the left
yyespixels from the top
--button BUTTONnoleftleft, middle, right
--doublenodouble-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
ArgumentRequiredDefaultChoicesDescription
ENV_IDyesenvironment ID from oo env list
textyesthe 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
ArgumentRequiredDefaultChoicesDescription
ENV_IDyesenvironment ID from oo env list
KEYSyessuch 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
ArgumentRequiredDefaultChoicesDescription
ENV_IDyesenvironment 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
ArgumentRequiredDefaultChoicesDescription
ENV_IDyesenvironment ID from oo env list
portyesthe 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
ArgumentRequiredDefaultChoicesDescription
ENV_IDyesenvironment ID from oo env list
portyesthe port on the machine, 1 to 65535
--yesnoconfirm 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
ArgumentRequiredDefaultChoicesDescription
ENV_IDyesenvironment ID from oo env list
portyesthe 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
ArgumentRequiredDefaultChoicesDescription
ENV_IDyesenvironment 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
ArgumentRequiredDefaultChoicesDescription
ENV_IDyesenvironment ID from oo env list
LOCAL:REMOTEyesthe 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
ArgumentRequiredDefaultChoicesDescription
ENV_IDyesenvironment 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
ArgumentRequiredDefaultChoicesDescription
ENV_IDyesenvironment ID from oo env list

It also takes the connection options.

On this page