Tutorials

End-to-end tutorials covering the most common Orquestio workflows. Each tutorial works both through the customer portal and the REST API.

---

1. Deploy your first OpenClaw agent

Go from zero to a running OpenClaw instance with a public URL.

Prerequisites

• An Orquestio account (sign up at orquestio.com).
• An API key for the orchestrator (generate one in Account Settings > API Keys in the portal), or use the portal directly.

Step 1 — Create the instance

Portal: Click New Instance, select the OpenClaw blueprint and openclaw-basic plan, enter an instance ID (e.g., my-agent), and click Create.

API:

curl -X POST https://api.orquestio.com/instances/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_id": "my-agent",
    "tenant_id": "your-tenant-id",
    "blueprint_name": "OpenClaw",
    "plan_id": "openclaw-basic"
  }'

Step 2 — Wait for provisioning

Portal: Watch the task progress bar on the instance detail page.

API: Poll the status endpoint until state is running:

curl https://api.orquestio.com/instances/my-agent/status \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "instance_id": "my-agent",
  "state": "running",
  "access_url": "https://my-agent.orquestio.com",
  "created_at": "2026-04-11T14:30:00Z"
}

Step 3 — Verify it works

Open the access_url in your browser, or hit the health endpoint:

curl https://api.orquestio.com/instances/my-agent/health

A healthy instance returns an HTTP 200 response with status details.

Step 4 — Configure your LLM key

Your OpenClaw instance needs at least one LLM API key to function. See Tutorial 2 below.

Tip

The entire process from account creation to a running instance typically takes under 5 minutes.

---

2. Configure LLM API keys

OpenClaw requires API keys for the LLM providers it will use (OpenAI, Anthropic, etc.). This tutorial shows how to set them securely.

Step 1 — Get your provider API key

Obtain an API key from your LLM provider:

• OpenAI: platform.openai.com/api-keys
• Anthropic: console.anthropic.com/settings/keys

Step 2 — Set the environment variable

Portal:

1. Open your instance detail page.
2. Go to the Environment tab.
3. Click Add Variable.
4. Set the key to OPENAI_API_KEY (or ANTHROPIC_API_KEY) and paste your key as the value.
5. Click Save.

API: Use the tasks endpoint to dispatch an environment update:

curl -X POST https://api.orquestio.com/instances/my-agent/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "set_env",
    "params": {
      "key": "OPENAI_API_KEY",
      "value": "sk-..."
    }
  }'

Step 3 — Set the default model (optional)

If you want to override the default LLM model, set the LLM_MODEL variable:

Portal: Add another environment variable with key LLM_MODEL and value gpt-4o (or claude-sonnet-4-20250514, etc.).

API:

curl -X POST https://api.orquestio.com/instances/my-agent/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "set_env",
    "params": {
      "key": "LLM_MODEL",
      "value": "gpt-4o"
    }
  }'

Step 4 — Verify the configuration

Hit your instance’s health endpoint to confirm the LLM connection is working:

curl https://api.orquestio.com/instances/my-agent/health

The response should show the LLM provider as connected.

Caution

Never share your LLM API keys publicly. Orquestio stores environment variables encrypted at rest and masks them in the portal UI.

---

3. Set up a custom domain

Replace the default *.orquestio.com URL with your own domain.

Prerequisites

• A running instance (see Tutorial 1).
• Access to your domain’s DNS settings.

Step 1 — Request the custom domain

Portal:

1. Open the instance detail page > Custom Domain tab.
2. Click Add Custom Domain.
3. Enter your domain, e.g., ai.example.com.

API:

curl -X POST https://api.orquestio.com/instances/my-agent/custom-domain \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "ai.example.com"}'

Step 2 — Get the CNAME target

Portal: The CNAME target is displayed immediately after submitting.

API:

curl https://api.orquestio.com/instances/my-agent/custom-domain \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "domain": "ai.example.com",
  "status": "pending_dns",
  "cname_target": "my-agent.cdn.orquestio.com"
}

Step 3 — Configure your DNS

In your DNS provider, create a CNAME record:

Type	Name	Target
CNAME	ai	my-agent.cdn.orquestio.com

Tip

If you use Cloudflare, keep the proxy status set to DNS only (grey cloud) during initial setup. You can enable the orange cloud after the certificate is issued.

Step 4 — Verify and wait for the certificate

Portal: Click Verify on the Custom Domain tab. Once DNS is confirmed, the certificate is issued automatically (Let’s Encrypt).

API: Poll the custom domain endpoint until status is active:

curl https://api.orquestio.com/instances/my-agent/custom-domain \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "domain": "ai.example.com",
  "status": "active",
  "cname_target": "my-agent.cdn.orquestio.com"
}

Step 5 — Test access

curl -I https://ai.example.com

You should receive an HTTP 200 with a valid TLS certificate.

---

4. Monitor and troubleshoot your instance

Learn how to check instance health, review logs, and handle common issues.

Checking instance health

Portal: The instance detail page shows a health indicator (green/yellow/red) updated every 30 seconds.

API:

curl https://api.orquestio.com/instances/my-agent/health \
  -H "Authorization: Bearer YOUR_API_KEY"

The health endpoint proxies a check to your actual instance and returns its status.

Reviewing operation logs

Every operation creates a task with a detailed log.

Portal: Go to instance detail > Tasks tab. Click any task to expand its log output.

API:

curl https://api.orquestio.com/instances/my-agent/tasks \
  -H "Authorization: Bearer YOUR_API_KEY"

Common issues and solutions

Instance stuck in provisioning

• Check the task log for the create operation.
• If it has been more than 10 minutes, the task likely failed silently. Try destroying and recreating the instance.

Instance shows error state

1. Open the latest task in the Tasks tab to see the error details.
2. Common causes: invalid environment variable values, resource limits exceeded.
3. Fix the root cause, then restart the instance.

Health check returns unhealthy

• Verify your LLM API key is valid and has sufficient quota.
• Check that the LLM_MODEL value matches a model your API key has access to.
• Review the instance logs for error messages.

Custom domain not working

• Confirm the CNAME record is correctly set: dig ai.example.com CNAME.
• Ensure the domain status in Orquestio is active, not pending_dns.
• If using Cloudflare, try setting proxy to DNS-only mode.

Tip

If you cannot resolve an issue through the portal and logs, contact support at [email protected] with your instance ID and the relevant task IDs.