Skip to content

Gremia Shell — Using the Desktop App

The Gremia Shell is a Tauri v2 desktop application that runs on your local machine. It loads a team_manifest.json from the cloud, spawns the required MCP servers, and connects to Gremia Cloud via an encrypted WebSocket tunnel.

Overview

graph TB
    subgraph Shell["Gremia Shell (Desktop)"]
        UI[React UI]
        Rust[Rust Backend]
        MCP1[MCP Server 1]
        MCP2[MCP Server 2]
        MCP3[MCP Server N]
    end

    Cloud[Gremia Cloud]

    UI --> Rust
    Rust --> MCP1
    Rust --> MCP2
    Rust --> MCP3
    Rust <-->|WebSocket + AES-256-GCM| Cloud

Signing In

  1. Launch the Shell application
  2. Enter your email and password
  3. If MFA is enabled, enter the 6-digit code from your authenticator app
  4. The Shell receives a JWT token used for all subsequent API calls

Session management

Sessions are stored securely in the OS keychain. You remain signed in until you explicitly log out or the token expires.

Loading a Manifest

After signing in, you can load a manifest in two ways:

From the cloud

  1. Click Load Manifest in the dashboard
  2. Browse your saved manifests (listed by name and creation date)
  3. Select one and click Load

From a file

  1. Click Import Manifest
  2. Select a team_manifest.json file from your filesystem
  3. The Shell validates it against the Zod schema before loading

Once loaded, the Shell displays:

  • Team name and description
  • Agent list with roles and model tiers
  • MCP server status (spawning, running, error)
  • Workflow graph visualization

MCP Server Lifecycle

When a manifest is loaded, the Shell spawns MCP servers defined in mcp_requirements:

stateDiagram-v2
    [*] --> Spawning: Manifest loaded
    Spawning --> Initializing: Process started
    Initializing --> Running: JSON-RPC handshake OK
    Initializing --> Error: Handshake failed
    Running --> Stopped: User stops / manifest unloaded
    Error --> Spawning: Retry
    Stopped --> [*]

Each MCP server runs as a child process communicating via stdio (stdin/stdout) using JSON-RPC 2.0.

The Shell performs the following for each server:

  1. Spawn — Start the process with the configured command, args, and environment
  2. Initialize — Send a JSON-RPC initialize request and wait for acknowledgement
  3. List Tools — Query available tools with tools/list
  4. Ready — Server is ready to receive tools/call requests

You can view the status of each server in the Servers panel.

Tunnel Connection

The tunnel is a WebSocket connection between the Shell and Gremia Cloud:

  1. Authentication — JWT is sent via the Sec-WebSocket-Protocol header
  2. Key exchange — Cloud generates an AES-256 session key and sends it to the Shell
  3. Encrypted messaging — All subsequent messages are encrypted with AES-256-GCM
  4. Heartbeat — Cloud sends heartbeats every 30 seconds to keep the connection alive

Reconnection

If the connection drops, the Shell reconnects automatically with exponential backoff:

Attempt Delay
1 2 seconds
2 4 seconds
3 8 seconds
... up to 64 seconds
10 Gives up

Tool Approval Flow

Some tool calls require human approval (when requires_approval: true in the agent definition):

  1. Cloud sends a tool_call message with requires_approval: true
  2. Shell displays an approval dialog showing:
  3. Server name and tool name
  4. Arguments to be passed
  5. You click Approve or Reject
  6. If approved, the Shell executes the tool and returns the result
  7. If rejected, the Shell sends an error result back to Cloud

Security-sensitive tools

Tools that modify files, send emails, or access external APIs should always have approvals_required: true in the manifest.

Certificate Management

The Shell uses mTLS (mutual TLS) for secure communication:

  • On first connection, the Shell generates an EC P-256 key pair
  • A Certificate Signing Request (CSR) is sent to /api/v1/certs/sign
  • Cloud signs the CSR and returns a 24-hour certificate
  • The cert rotation loop checks every 5 minutes and renews 1 hour before expiry

View certificate status in Settings > Security > Certificates.

Auto-Updates

The Shell checks for updates every 6 hours:

  • Notification — A banner appears when an update is available
  • Manual check — Go to Settings > Check for Updates
  • Install — Click Update Now to download, install, and restart

Updates are signed and verified before installation.

Keyboard Shortcuts

Shortcut Action
Ctrl+N New task
Ctrl+L Load manifest
Ctrl+, Open settings
Ctrl+Q Quit
Ctrl+R Reconnect tunnel

Troubleshooting

MCP server fails to start

  • Check that the command exists on your PATH (e.g., npx, uvx)
  • Verify environment variables in the manifest are set correctly
  • Check the Server Logs panel for stderr output

Tunnel disconnects frequently

  • Ensure stable internet connectivity
  • Check if a firewall or proxy is interrupting WebSocket connections
  • Look for tunnel:error events in the Shell console

High memory usage

  • Each MCP server runs as a separate process; more servers = more memory
  • Stop unused servers from the Servers panel
  • Consider reducing the number of agents in your manifest