Skip to content

Sandboxing and information control

URSA is designed for powerful scientific workflows. Some agents can write files, run shell commands, read local files, call web tools, and connect to external MCP servers. This power requires careful information-control practices.

Use a dedicated workspace

Run URSA in a workspace created for the task:

mkdir ursa-workspace
cd ursa-workspace
ursa --config ../config.yaml

Avoid running execution workflows directly inside repositories, home directories, credential directories, or folders containing sensitive data unless that is intentional.

Understand execution risk

The Execution Agent can:

  • create and edit files,
  • run shell commands,
  • install or import packages, including when resolving missing dependencies,
  • inspect outputs and continue iterating.

Potential risks include:

  • modifying or deleting files,
  • leaking data through prompts, network calls, or logs,
  • running expensive or long-lived processes,
  • executing unsafe generated code.

Use a virtual machine, container, dedicated user account, or isolated environment for high-risk tasks.

File access outside the workspace

The workspace is a working directory, not a filesystem security boundary. read_file intentionally permits reading files outside it without an LLM safety assessment, so workflows can access existing inputs and reference files. Relative paths are resolved from the workspace; absolute paths, ../ paths, and symlinks can reach other files readable by the URSA process. File contents may be sent to the configured model as tool results.

Although write_code checks that its target resolves inside the workspace, this does not isolate the agent: shell commands and other tools retain the host process's permissions. Use operating-system permissions or an isolated environment to restrict access to files.

Command screening

Set the URSA_SAFETY_LEVEL environment variable before launching URSA to select the LLM screening policy for run_command. Values are case-insensitive.

Value Behavior
default (also used when unset) Assesses the command with trust assumptions for configured executables, agent-created files, and LaTeX-related operations. The prompt also treats package installation for configured executables as safe.
low Asks the model to scrutinize destructive commands and flag high-concern attempts to extract sensitive information, while trusting workspace files.
trusted Still calls the model, but supplies only a generic statement that the agent is trusted, without the proposed command. This does not provide a command-specific assessment.
none or yolo Bypasses the LLM assessment and proceeds to command execution.

Unrecognized values use the default prompt. These policies are model judgments, not deterministic restrictions: they can accept unsafe commands or reject legitimate ones. They do not screen read_file or provide filesystem or network isolation.

Command timeout

run_command executes through a shell with a fixed timeout of 600,000 seconds (approximately seven days). There is currently no configuration option for this timeout. A command containing an infinite loop can therefore occupy a run for a long time.

For workloads requiring a shorter limit, use an external job scheduler or process supervisor with an appropriate wall-time limit.

Web tools are opt in

URSA web tools are opt in for information-control reasons. They are disabled by default in core CLI configuration.

Enable them only when you want URSA to make network requests through web-search tools:

use_web: true

or:

ursa --config config.yaml --use-web

When web tools are enabled, URSA may query search services or retrieve web pages as part of an agent workflow. Do not enable web tools for data that should remain fully local.

Use groups to restrict endpoints

Security groups can restrict which model endpoint base URLs are allowed:

allowed_base_urls:
  - https://api.openai.com
  - http://localhost:11434

Create and use a group:

ursa create-group research allowed_urls.yaml
ursa --config config.yaml --group research --name research-agent

Use narrow allowlists for sensitive projects. See Groups and endpoint security.

Be careful with MCP servers

MCP servers can expose powerful external tools. Only connect MCP servers that you trust, and do not run the URSA MCP server as a shared multi-user service without adding isolation.

Protect secrets

  • Prefer api_key environment references rather than literal API keys in YAML files.
  • In the desktop dashboard, prefer Keyring so keys are kept out of configuration files.
  • Do not store API keys in persistent agent names or prompts.
  • Review shared agent archives before distributing them.
  • Avoid committing project-specific config files that contain endpoint secrets.

Dashboard-stored model credentials are bound to their provider or endpoint origin. Changing the endpoint host requires saving the key again. The dashboard passes a key to its worker through a one-time private pipe and removes credential-like variables from the worker environment so agent-launched commands do not inherit model API keys.

Containerization options

Containers can provide partial isolation. The exact command depends on your environment, but the general pattern is:

  1. mount only the workspace URSA needs,
  2. pass only the environment variables URSA needs,
  3. avoid mounting your full home directory,
  4. run as a non-root user where practical.

The repository README includes Docker and Charliecloud examples for containerized execution.

Responsible-use checklist

Before running an execution or web-enabled workflow, ask:

  • Am I in a dedicated workspace?
  • Does this task need web access?
  • Does this task need access to sensitive files?
  • Is the model endpoint approved for this data?
  • Should I use a local endpoint or isolated container?
  • Am I comfortable sharing any generated persistent state?