@freestyle-sh/with-opencode

@freestyle-sh/with-opencode

OpenCode integration for Freestyle VMs. Provides a fully configured OpenCode AI coding assistant server in your Freestyle VM.

Installation

bun add @freestyle-sh/with-opencode freestyle

Usage

Basic Setup

import { freestyle, VmSpec } from "freestyle";
import { VmOpenCode } from "@freestyle-sh/with-opencode";

const { vm } = await freestyle.vms.create({
  spec: new VmSpec({
    with: {
      opencode: new VmOpenCode(),
    },
  }),
});

// Expose the web UI
const { url } = await vm.opencode.routeWeb();
console.log(`OpenCode UI: ${url}`);

Using the API Client

const { client } = await vm.opencode.client();

// Use the OpenCode SDK client to interact with the server
const sessions = await client.session.list();

With Custom Domain

const { url } = await vm.opencode.routeWeb({
  domain: "my-opencode.example.com",
});

const { client } = await vm.opencode.client({
  domain: "my-opencode-api.example.com",
});

With Authentication

import { freestyle, VmSpec } from "freestyle";
import { VmOpenCode } from "@freestyle-sh/with-opencode";

const { vm } = await freestyle.vms.create({
  spec: new VmSpec({
    with: {
      opencode: new VmOpenCode({
        server: {
          username: "serveradmin",
          password: "secret-server-pass",
        },
        web: {
          username: "webadmin",
          password: "secret-web-pass",
        },
      }),
    },
  }),
});

// URLs will include credentials automatically
const { url } = await vm.opencode.routeWeb();
const { client } = await vm.opencode.client();

Options

new VmOpenCode({
  server: {
    port: 4096, // Optional: API server port (default: 4096)
    username: "admin", // Optional: Basic auth username (default: "opencode" when password is set)
    password: "secret", // Optional: Basic auth password
  },
  web: {
    port: 4097, // Optional: Web UI port (default: 4097)
    username: "admin", // Optional: Basic auth username (default: "opencode" when password is set)
    password: "secret", // Optional: Basic auth password
  },
  env: {
    ANTHROPIC_API_KEY: "sk-ant-...", // Optional: Environment variables for OpenCode
  },
});

Option	Type	Default	Description
server.port	number	4096	Port for the OpenCode API server
server.username	string	"opencode"	Basic auth username (only used if password set)
server.password	string	-	Basic auth password for the API server
web.port	number	4097	Port for the OpenCode web UI
web.username	string	"opencode"	Basic auth username (only used if password set)
web.password	string	-	Basic auth password for the web UI
env	Record<string, string>	{}	Environment variables passed to OpenCode processes

Environment Variables

OpenCode requires API keys to interact with AI providers. When running in a Freestyle VM, pass the required keys using the env option.

Note: Environment variables are stored as plain text in the VM's startup scripts. Users with direct or indirect access to the VM may be able to view these values. Use appropriately scoped API keys and rotate them if the VM is shared or exposed.

Variable	Description
ANTHROPIC_API_KEY	API key for Claude models
OPENAI_API_KEY	API key for OpenAI models
OPENROUTER_API_KEY	API key for OpenRouter

See OpenCode Providers for all supported providers and their environment variables.

const { vm } = await freestyle.vms.create({
  spec: new VmSpec({
    with: {
      opencode: new VmOpenCode({
        env: {
          ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY!,
        },
      }),
    },
  }),
});

API

vm.opencode.routeWeb(options?)

Exposes the OpenCode web UI on a public domain.

Options:

• domain?: string - Custom domain to use. If not specified, generates a random subdomain.

Returns: Promise<{ url: string }> - URL includes credentials if authentication is configured.

const { url } = await vm.opencode.routeWeb();
console.log(`OpenCode UI available at: ${url}`);

vm.opencode.client(options?)

Creates an OpenCode SDK client connected to the server. The client is automatically configured with credentials if authentication is enabled.

Options:

• domain?: string - Custom domain for the API endpoint. If not specified, generates a random subdomain.

Returns: Promise<{ client: OpencodeClient }>

const { client } = await vm.opencode.client();

// List sessions
const sessions = await client.session.list();

// Create a new session
const session = await client.session.create({ path: "/workspace" });

vm.opencode.serverPort()

Returns the configured API server port.

Returns: number

vm.opencode.webPort()

Returns the configured web UI port.

Returns: number

How It Works

The package uses systemd services to install and run OpenCode during VM creation:

• Installs OpenCode via the official install script
• Starts the OpenCode API server (opencode serve)
• Starts the OpenCode web UI (opencode web)

Both services are configured to restart automatically and listen on all interfaces (0.0.0.0).

Documentation

• Freestyle Documentation
• OpenCode Documentation