Instances API

Manage OpenCode instances

Overview

The Instances API provides information about running OpenCode instances managed by the Portal.

List Instances

Retrieve all running OpenCode instances.

GET /api/instances

Authentication

No authentication required.

Response

total · number

Total number of running instances

instances · array

Array of instance objects

Show Instance object

id · string

Unique instance identifier

name · string

Human-readable instance name

directory · string

Absolute path to the project directory

port · number

OpenCode instance port number

hostname · string

Hostname where the instance is running (e.g., “localhost”, “0.0.0.0”)

opencodePid · number

Process ID of the OpenCode server (null for Docker instances)

webPid · number

Process ID of the web server

startedAt · string

ISO 8601 timestamp when the instance was started

instanceType · string

Type of instance: process or docker

containerId · string

Docker container ID (only for Docker instances)

state · string

Current state: running

status · string

Human-readable status message

Example

curl http://localhost:3000/api/instances

Response

{
  "total": 2,
  "instances": [
    {
      "id": "inst_abc123",
      "name": "my-web-app",
      "directory": "/home/user/projects/my-web-app",
      "port": 3100,
      "hostname": "localhost",
      "opencodePid": 12345,
      "webPid": 12346,
      "startedAt": "2026-03-03T09:00:00.000Z",
      "instanceType": "process",
      "containerId": null,
      "state": "running",
      "status": "Running since 3/3/2026, 9:00:00 AM"
    },
    {
      "id": "inst_def456",
      "name": "api-service",
      "directory": "/home/user/projects/api-service",
      "port": 3101,
      "hostname": "0.0.0.0",
      "opencodePid": null,
      "webPid": 12347,
      "startedAt": "2026-03-03T10:30:00.000Z",
      "instanceType": "docker",
      "containerId": "abc123def456",
      "state": "running",
      "status": "Running since 3/3/2026, 10:30:00 AM"
    }
  ]
}

---

Instance Types

Process Instances

Instances running as native OS processes:

• instanceType: "process"
• opencodePid: Valid process ID
• containerId: null

Docker Instances

Instances running in Docker containers:

• instanceType: "docker"
• opencodePid: null
• containerId: Docker container ID

---

Use Cases

Dashboard Display

Display all running instances in a web interface:

async function loadInstances() {
  const response = await fetch('http://localhost:3000/api/instances');
  const { total, instances } = await response.json();
  
  console.log(`${total} instance(s) running:`);
  instances.forEach(instance => {
    console.log(`- ${instance.name} (${instance.directory})`);
    console.log(`  Port: ${instance.port}`);
    console.log(`  Status: ${instance.status}`);
  });
}

Health Monitoring

Monitor instance health:

import requests
import time

def monitor_instances():
    while True:
        response = requests.get('http://localhost:3000/api/instances')
        data = response.json()
        
        print(f"Running instances: {data['total']}")
        
        for instance in data['instances']:
            print(f"  {instance['name']}: {instance['state']}")
            
            if instance['instanceType'] == 'docker':
                print(f"    Container: {instance['containerId'][:12]}")
            else:
                print(f"    PID: {instance['opencodePid']}")
        
        time.sleep(30)

Instance Discovery

Find instances by directory or name:

async function findInstanceByDirectory(directory) {
  const response = await fetch('http://localhost:3000/api/instances');
  const { instances } = await response.json();
  
  return instances.find(inst => inst.directory === directory);
}

const instance = await findInstanceByDirectory('/home/user/projects/my-app');
if (instance) {
  console.log(`Instance running on port ${instance.port}`);
} else {
  console.log('No instance found for this directory');
}

---

Notes

Only running instances are returned. Stopped instances are automatically filtered out.

The instance list is read from ~/.portal.json and filtered to show only currently running processes or containers.

Process IDs (opencodePid, webPid) are platform-specific and should not be used for long-term reference. Use the id field for persistent identification.

Use the port field to construct API URLs for instance-specific endpoints:

http://localhost:3000/api/opencode/{port}/sessions

---

Additional Endpoints

Get Project Information

Retrieve current project information for an instance:

GET /api/opencode/:port/project/current

Path Parameters

port · number · required

The OpenCode instance port number

Response

name · string

Project name

worktree · string

Absolute path to project directory

repository · string

Git repository URL if available

Example

curl http://localhost:3000/api/opencode/3100/project/current

Response

{
  "name": "my-web-app",
  "worktree": "/home/user/projects/my-web-app",
  "repository": "https://github.com/user/my-web-app.git"
}

---

Health Check

Check if an OpenCode instance is healthy:

GET /api/opencode/:port/health

Path Parameters

port · number · required

The OpenCode instance port number

Response

healthy · boolean

Whether the instance is healthy and responding

port · number

The instance port number

Example

curl http://localhost:3000/api/opencode/3100/health

Response

{
  "healthy": true,
  "port": 3100
}

---

Get Configuration

Retrieve OpenCode configuration for an instance:

GET /api/opencode/:port/config

Path Parameters

port · number · required

The OpenCode instance port number

Example

curl http://localhost:3000/api/opencode/3100/config

---

Get Providers

Retrieve available AI providers for an instance:

GET /api/opencode/:port/providers

Path Parameters

port · number · required

The OpenCode instance port number

Response

providers · array

Array of available AI provider configurations

Example

curl http://localhost:3000/api/opencode/3100/providers

Response

{
  "providers": [
    {
      "id": "anthropic",
      "name": "Anthropic",
      "models": ["claude-4.5-sonnet", "claude-3-opus"]
    },
    {
      "id": "openai",
      "name": "OpenAI",
      "models": ["gpt-4", "gpt-3.5-turbo"]
    }
  ]
}

---

Get Agents

Retrieve available agents for an instance:

GET /api/opencode/:port/agents

Path Parameters

port · number · required

The OpenCode instance port number

Response

agents · array

Array of available agent configurations

Example

curl http://localhost:3000/api/opencode/3100/agents

---

System Endpoints

Get System Hostname

Retrieve the system hostname where Portal is running:

GET /api/system/hostname

Authentication

No authentication required.

Response

hostname · string

The system hostname

Example

curl http://localhost:3000/api/system/hostname

Response

{
  "hostname": "my-server"
}

Use Cases

This endpoint is useful for:

• Displaying the server name in the UI
• Identifying which server you’re connected to when managing multiple instances
• Debugging connection issues in remote setups