Overview The Instances API provides information about running OpenCode instances managed by the Portal.
List Instances Retrieve all running OpenCode instances.
Authentication No authentication required.
Response Total number of running instances
Array of instance objects Unique instance identifier
Human-readable instance name
Absolute path to the project directory
OpenCode instance port number
Hostname where the instance is running (e.g., “localhost”, “0.0.0.0”)
Process ID of the OpenCode server (null for Docker instances)
Process ID of the web server
ISO 8601 timestamp when the instance was started
Type of instance: process or docker
Docker container ID (only for Docker instances)
Human-readable status message
Example curl http://localhost:3000/api/instances
{ "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 IDcontainerId: null
Docker Instances Instances running in Docker containers:
instanceType: "docker"opencodePid: nullcontainerId: 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 Retrieve current project information for an instance:
GET /api/opencode/:port/project/current
Path Parameters The OpenCode instance port number
Response Absolute path to project directory
Git repository URL if available
Example curl http://localhost:3000/api/opencode/3100/project/current
{ "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 The OpenCode instance port number
Response Whether the instance is healthy and responding
Example curl http://localhost:3000/api/opencode/3100/health
{ "healthy" : true , "port" : 3100 }
Get Configuration Retrieve OpenCode configuration for an instance:
GET /api/opencode/:port/config
Path Parameters 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 The OpenCode instance port number
Response Array of available AI provider configurations
Example curl http://localhost:3000/api/opencode/3100/providers
{ "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 The OpenCode instance port number
Response 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:
Authentication No authentication required.
Response Example curl http://localhost:3000/api/system/hostname
{ "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