Configuration¶

This page shows where OpenShell keeps its settings, how sandboxes are configured, and how to connect an agent to a model provider.

Run every openshell command as the ubuntu user. From a Session Manager session, switch first with sudo -iu ubuntu.

Where things live¶

What	Where
Gateway configuration	`/home/ubuntu/.config/openshell/gateway.toml`
Gateway environment (telemetry off)	`/home/ubuntu/.config/openshell/gateway.env`
Gateway state and TLS material	`/home/ubuntu/.local/state/openshell/`
Gateway service	`openshell-gateway`, a systemd user service of `ubuntu`
First-boot service	`sushi-openshell`, a system service
Walkthrough script	`/opt/sushi/docs/demo.sh`

The TLS directory holds this instance's private keys. Keep it private, and never paste its contents into a support message.

Gateway defaults¶

First boot writes gateway.toml with these settings:

Setting	Value
Gateway name	`sushi-openshell`
Listen address	`127.0.0.1:17670`
Compute driver	`docker`
Image pull policy	`if_not_present`
Host bind mounts	Off

The CLI is registered with this gateway under the name sushi. The default sandbox, supervisor and workload images are preloaded, so creating a sandbox does not need to download anything.

Keep the gateway on loopback

The gateway is an administrative API. Do not change the listen address to a public interface, and do not open port 17670 in a security group. Changing a security group alone does not make a public administration API safe.

After you edit gateway.toml, restart the gateway:

systemctl --user restart openshell-gateway
openshell status

Sandboxes and policies¶

Every sandbox runs under an OpenShell policy. The default policy denies outbound network access, so a new sandbox cannot reach the internet. To let a workload reach an endpoint, write a policy that names the exact endpoints and programs it needs, and pass it when you create the sandbox:

openshell sandbox create --name work --cpu 1 --memory 512Mi \
  --policy <policy.yaml> --detach -- /bin/sleep 600

Useful commands:

openshell sandbox list --names
openshell sandbox get <name> -o json
openshell sandbox delete <name>

Run openshell --help or openshell sandbox create --help for every option in the installed version.

Connect an AI model provider¶

You do not need a provider to run sandboxes, shell commands or file processing. For AI-generated responses, run your own agent or API client in a sandbox and connect it to a model endpoint through an OpenShell provider.

OpenShell 0.1.2 supports provider profiles and attaching a provider to a sandbox. This outline assumes a provider profile you have reviewed, with ID my-profile, a reviewed policy, your own agent image and credentials already available in the ubuntu user's local state:

openshell provider profile lint -f reviewed-provider.yaml
openshell provider profile import -f reviewed-provider.yaml
openshell provider create --name my-provider --type my-profile --from-existing
openshell sandbox create --name ai-work --from my-agent:version \
  --provider my-provider --policy reviewed-policy.yaml -- my-agent

Check the exact options with openshell provider create --help. Both the provider profile and the sandbox policy must allow the call your agent makes.

Keep secrets out of commands

Configure credentials through the provider's supported mechanism. Do not put real keys on the command line, in sandbox --env, in source files, images or EC2 user data.