Documentation
Core Concepts
Selective Elevation

Selective Elevation

Selective Elevation allows agents to perform specific host-side operations through controlled “remote calls” - commands that run on the host from inside the sandbox.

The Problem

Containers provide isolation, but sometimes agents need to interact with the host:

  • Flash firmware to a development board
  • Deploy code to a server
  • Run a build script that needs host resources
  • Interact with host-side services
  • Trigger verification workflows

Simply giving the container host access defeats the purpose of sandboxing. Selective elevation provides a middle ground: curated, specific host operations.

How It Works

  1. You define remote calls in your resource sets
  2. Shai starts an MCP server on the host
  3. Inside the container, agents invoke calls via shai-remote
  4. The MCP server executes the command on the host
  5. Output is returned to the agent
┌─────────────────────────────────────┐
│         Container (Sandbox)         │
│                                     │
│  Agent runs:                        │
│  $ shai-remote deploy-staging         │
│              │                      │
└──────────────┼──────────────────────┘
               │
               │ (MCP protocol)
               │
┌──────────────▼──────────────────────┐
│         Host (Your Machine)         │
│                                     │
│  MCP Server executes:               │
│  /usr/local/bin/deploy.sh           │
│                                     │
└─────────────────────────────────────┘

Defining Remote Calls

Remote calls are defined in the calls section of a resource set:

 1# .shai/config.yaml
 2resources:
 3  deployment:
 4    calls:
 5      - name: deploy-staging
 6        description: Deploy to staging environment
 7        command: /usr/local/bin/deploy.sh
 8        allowed-args: '^--env=staging$'
 9
10      - name: run-integration-tests
11        description: Run integration tests on host
12        command: /usr/local/bin/test-runner.sh

Fields:

  • name: Unique identifier for the call (used with shai-remote)
  • description: Human-readable description of what the call does
  • command: Absolute path to the host command
  • allowed-args: (Optional) Regex pattern to validate arguments

Invoking Remote Calls

Inside the sandbox, use the shai-remote command:

1# No arguments
2shai-remote run-integration-tests
3
4# With arguments (validated against allowed-args regex)
5shai-remote deploy-staging --env=staging

The command runs on the host, and output is streamed back to the container.

shai-remote is automatically available inside all Shai sandboxes. You don’t need to install anything.

Argument Filtering

The allowed-args field provides security through argument validation:

1calls:
2  - name: flash-device
3    description: Flash firmware to USB device
4    command: /usr/local/bin/flash.sh
5    allowed-args: '^--port=/dev/ttyUSB[0-9]+$'

What this does:

  • Allows: shai-remote flash-device --port=/dev/ttyUSB0 ✅
  • Allows: shai-remote flash-device --port=/dev/ttyUSB1 ✅
  • Blocks: shai-remote flash-device --port=/dev/sda ❌
  • Blocks: shai-remote flash-device --rm -rf / ❌
Always use argument filtering unless the call takes no arguments. This prevents agents from injecting malicious commands.

Multiple Arguments

The regex validates the entire argument string:

1calls:
2  - name: deploy
3    description: Deploy to environment
4    command: /usr/local/bin/deploy.sh
5    allowed-args: '^--env=(staging|production) --region=us-\w+-\d+$'

Valid:

1shai-remote deploy --env=staging --region=us-east-1
2shai-remote deploy --env=production --region=us-west-2

Invalid:

1shai-remote deploy --env=dev --region=us-east-1      # env=dev not allowed
2shai-remote deploy --env=staging                     # missing --region

No Argument Validation

If a command takes no arguments, omit allowed-args:

1calls:
2  - name: trigger-build
3    description: Trigger CI build
4    command: /usr/local/bin/trigger-build.sh
5    # No allowed-args means no arguments are permitted

Use Cases

Firmware Flashing 

1resources:
2  embedded-dev:
3    calls:
4      - name: flash-firmware
5        description: Flash compiled firmware to device
6        command: /usr/local/bin/flash.sh
7        allowed-args: '^--device=/dev/ttyUSB[0-9]+ --binary=/tmp/firmware-\w+\.bin$'

Agent workflow:

  1. Compile firmware inside sandbox
  2. Copy binary to /tmp/firmware-xyz.bin
  3. shai-remote flash-firmware --device=/dev/ttyUSB0 --binary=/tmp/firmware-xyz.bin

Deployment Verification 

1resources:
2  deployment:
3    calls:
4      - name: verify-deployment
5        description: Verify deployment succeeded
6        command: /usr/local/bin/verify.sh
7        allowed-args: '^--service=[\w-]+ --env=(staging|production)$'

Agent workflow:

  1. Deploy code (via other means)
  2. shai-remote verify-deployment --service=api --env=staging
  3. Check exit code to confirm deployment

Secret Fetching 

1resources:
2  secret-access:
3    calls:
4      - name: fetch-secrets
5        description: Fetch secrets from host vault
6        command: /usr/local/bin/fetch-secrets.sh
7        allowed-args: '^--env=(dev|staging|production)$'
Be careful with secret-fetching calls. Ensure the host script validates the caller and logs access.

Build Triggering 

1resources:
2  ci-integration:
3    calls:
4      - name: trigger-ci
5        description: Trigger CI pipeline
6        command: /usr/local/bin/trigger-ci.sh
7        allowed-args: '^--branch=[\w/-]+ --pipeline=[\w-]+$'

Database Operations 

 1resources:
 2  db-admin:
 3    calls:
 4      - name: create-migration
 5        description: Create database migration
 6        command: /usr/local/bin/create-migration.sh
 7        allowed-args: '^--name=[\w_]+$'
 8
 9      - name: rollback-migration
10        description: Rollback last migration
11        command: /usr/local/bin/rollback.sh
12        allowed-args: '^--steps=[1-9]$'

Security Considerations

✅ Do

  • Validate arguments rigorously with allowed-args
  • Use absolute paths for commands
  • Keep host scripts simple and auditable
  • Log all call invocations on the host
  • Treat calls as security-sensitive boundaries
  • Use calls sparingly - prefer in-container operations

❌ Don’t

  • Allow arbitrary arguments without regex validation
  • Give calls shell access (command: /bin/bash)
  • Allow file path arguments without strict validation
  • Trust user input without validation
  • Use calls for operations that could run in-container

Argument Injection Risks

Bad:

1calls:
2  - name: deploy
3    command: /bin/bash -c "deploy.sh"
4    allowed-args: '.*'    # ❌ Allows anything!

Good:

1calls:
2  - name: deploy
3    command: /usr/local/bin/deploy.sh
4    allowed-args: '^--env=(staging|production)$'    # ✅ Strict validation

Debugging Calls

List Available Calls

Inside the sandbox:

1shai-remote --list

Shows all calls available in your current resource sets.

Test Calls

Manually test calls to verify behavior:

1shai -rw . --resource-set deployment
2# Inside sandbox:
3shai-remote deploy-staging --env=staging

Host Script Output

Host script stdout/stderr is sent back to the container. Use this for debugging:

1#!/bin/bash
2# /usr/local/bin/deploy.sh
3
4echo "Starting deployment..." >&2
5echo "Arguments: $@" >&2
6
7# Do deployment work...
8
9echo "Deployment complete!"

Call Uniqueness

Within a single workspace path, all call names must be unique:

 1resources:
 2  set-a:
 3    calls:
 4      - name: deploy
 5        command: /usr/local/bin/deploy-a.sh
 6
 7  set-b:
 8    calls:
 9      - name: deploy        # ❌ Error if both sets apply to same path
10        command: /usr/local/bin/deploy-b.sh

If you need multiple deployment calls, use distinct names:

 1resources:
 2  staging-deploy:
 3    calls:
 4      - name: deploy-staging
 5        command: /usr/local/bin/deploy-staging.sh
 6
 7  production-deploy:
 8    calls:
 9      - name: deploy-production
10        command: /usr/local/bin/deploy-production.sh

Alternatives to Remote Calls

Before using remote calls, consider if the operation can happen in-container:

GoalIn-Container Alternative
Access secretsMount secret files read-only
Run testsInstall test tools in the image
Build artifactsUse multi-stage builds
Network accessAdd to HTTP allowlist

Remote calls are best for operations that must interact with host-specific resources (hardware devices, host-only services, etc.).

Next Steps

Apply RulesHow Shai Works