​
Core Concepts

WithGiga is built around five primary objects. Understanding how they relate to each other makes everything else click.

​
Deployments

A Deployment is a named, persistent configuration for a cloud computer. Think of it as the container that owns a sandbox, tracks its history, and holds billing metadata.
  • You create a deployment once; it can be started, stopped, restarted, and extended
  • Deployments have a platform (the OS template), a duration (how long the sandbox stays alive), and optional AI prompts
  • The deployment’s status reflects the state of its underlying sandbox: provisioning → running → stopped → terminated
  • All file uploads, session history, and usage are scoped to the deployment

​
Sessions (Threads)

A Session (also called a Thread) is the conversational context for an AI agent within a deployment. It holds the message history and configuration passed to the agent.
  • Every deployment has one active session at a time
  • The session stores the userPrompt, goalPrompt, and optional systemPrompt
  • Sessions are identified by a threadId (UUID)

​
Runs

A Run is a single execution of the AI agent within a session — the act of the agent actually doing work on the computer.
  • Starting a run provisions (or resumes) a sandbox and begins AI execution
  • Each run has a lifecycle: QUEUED → RUNNING → COMPLETED / FAILED
  • A run returns a publicAccessToken you can use to subscribe to real-time progress via Trigger.dev
  • The run’s metadata contains the live sandboxId and vncUrl once the sandbox is ready

​
Sandboxes

A Sandbox is the actual isolated virtual machine — a real Ubuntu 22.04 desktop running in the cloud.
  • Sandboxes are provisioned on demand when a run starts
  • They expose a VNC endpoint (vncUrl) for live desktop streaming
  • Sandboxes have a default lifetime of 15 minutes, extendable in 15-minute increments via POST /api/sandbox/extend
  • Available resource tiers:
TemplatevCPURAMCost
giga-standard24 GB$0.20/hr
giga-mini12 GB$0.10/hr
giga-pro48 GB$0.40/hr
giga-max816 GB$0.80/hr

​
API Keys

An API Key is your credential for authenticating requests to api.withgiga.ai.
  • Keys start with giga_sk_ followed by 32 hex characters
  • They are workspace-scoped and rotatable without downtime
  • Pass the key in every request: Authorization: Bearer giga_sk_...
  • Generate and revoke keys from Profile → API Keys in the dashboard or via POST /api/keys

​
How they fit together

API Key
  └── authenticates requests to →
        Deployment (named config + billing owner)
          └── has one active → Session (thread / message history)
                └── triggers → Run (AI execution)
                      └── provisions → Sandbox (live Ubuntu VM + VNC)
                            └── exposes → Files (S3-backed, sync in/out)
When you call POST /api/deployments/start, WithGiga creates a Deployment, opens a Session, starts a Run, and boots a Sandbox — all in one request.