---
title: "Processes"
description: "Run commands, terminals and code in a sandbox."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.jgcp.mistrivedev.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Processes

A process is anything that runs in a sandbox: a command, a terminal or a piece of code. All three are the same resource, with a `kind` of `COMMAND`, `TERMINAL` or `CODE`.

## Run a process and wait

`run` starts a process and waits for it to end. It returns the process with its exit and its output.

`run` waits up to `wait` seconds. If the process is still running when the wait ends, it keeps running and the result has no exit. Call `wait` on the process to wait again.

`wait` is how long your call waits. `timeout` is when Sutra ends the process. They are separate settings, and an unset `timeout` means the process has no limit.

## Exit

A process that has ended has an `exit` with a `reason`:

| Reason | Meaning |
| --- | --- |
| `EXITED` | The process ended on its own. `code` holds its exit code. |
| `SIGNALED` | A signal ended the process. `signal` holds its name. |
| `TIMED_OUT` | The process reached its `timeout`. |
| `LOST` | Sutra lost track of the process and cannot report how it ended. |

A non-zero exit code is a result, not an error. The call succeeds, and you decide what the code means. Sutra never runs a process again on its own.

## Start a long-running process

`start` returns as soon as the process has started. Use it for servers and other work that runs in the background.

To end a process, send it a signal. Pass `escalateAfter` to send `SIGKILL` if it is still running after that many seconds.

## Output

Sutra keeps the output of every process. Read it in pages with `readOutput`, or stream it with `streamOutput`. Each chunk carries a cursor: pass it back to continue from where you stopped.

## Terminals and code

A `TERMINAL` process runs in a pseudo-terminal with `columns` and `rows`. Write to it with `writeInput`, change its size with `resize`, and attach to it over a two-way stream.

A `CODE` process runs a snippet in a `language`: `python`, `javascript`, `typescript` or `bash`. It has the same exit and output as a command.

:::note[Today]
Today you run a process and wait for it with `exec` (`sandbox.exec` in the SDKs, `anchor sandbox exec` in the CLI). Its `timeout` is 1 to 300 seconds, and 60 seconds when you leave it out. A command that is still running when the timeout ends is an error, `DEADLINE_EXCEEDED`, and it keeps running in the sandbox. A command the sandbox cannot run, because it does not exist, is not executable or its working folder does not exist, is `FAILED_PRECONDITION`. So is output larger than 4 MiB: write it to a file and read the file.

You start a process with `processes.start`. A command that cannot be started is `FAILED_PRECONDITION`, and the process is kept in the state `PROCESS_ERROR`; start again with a new process id. `wait` waits at most 300 seconds; call it again to wait longer. You read output by byte offset with `logs`. `kill` ends the process and its children with `SIGKILL` at once and takes no other signal.

A code process is `execCodeRun` (`exec_code_run` in Python), with the language `shell`, `sh` or `python`. Terminals, input, output streaming and signals are not available yet.

Processes run as the user `anchor` in `/home/anchor`, and `sudo` needs no password. Files a process creates get the mode `0644`, and folders `0755`. The search path includes `/usr/local/bin` and `~/.local/bin`, so a tool installed with `npm install -g` or `pip install --user` runs by its name. Environment variables you pass reach the process only if their names are upper case letters, digits and `_`. `PATH`, `HOME`, `USER`, `LOGNAME`, `SHELL`, `PYTHONHOME`, `PYTHONPATH` and names that start with `LD_` are dropped; to change the search path, set it inside the command.
:::

Source: https://docs.jgcp.mistrivedev.com/sandboxes/processes/index.mdx
