Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.corsair.dev/llms.txt

Use this file to discover all available pages before exploring further.

Instances are the main provisioning boundary in Corsair Hosted. An instance owns installed plugins, permission policies, shared integration credentials, tenants, and the runtime cache used by MCP and direct execution. 
const { id } = await corsair.instances.create({ name: "prod" });
const inst = corsair.instance(id);

​
List and create instances

const { instances } = await corsair.instances.list();

for (const instance of instances) {
  console.log(instance.id, instance.name, instance.status);
}

const instance = await corsair.instances.create({
  name: "staging",
});

console.log(instance.id);
console.log(instance.mcpHttpUrl);
console.log(instance.oauthCallbackUrl);
Instance names cannot contain spaces. Use names like prod, staging, or acme-prod.

​
Read, update, and delete an instance

const inst = corsair.instance(instanceId);

const detail = await inst.get();
await inst.update({ name: "prod-v2" });
await inst.update({ status: "suspended" });
inst.delete() permanently removes the hosted instance, its provisioned database, tenants, credentials, MCP keys, and runtime state.
await inst.delete();

​
Install or update plugins

Use inst.plugins.upsert() to install a plugin or update its configuration. 
await inst.plugins.upsert("slack", {
  mode: "cautious",
});

await inst.plugins.upsert("github", {
  authType: "oauth_2",
  useManaged: true,
});

await inst.plugins.upsert("linear", {
  mode: "strict",
  overrides: {
    "api.issues.delete": "deny",
  },
});
The SDK narrows authType to the selected plugin. For example, "gmail" accepts OAuth, while "linear" accepts API-key auth.

​
Plugin modes

Plugin modes define the default policy for operations in that plugin.
ModeRecommended use
openInternal tooling where your app already gates every action
cautiousGeneral agent use with safe reads and approval gates for risky writes
strictHigher-risk environments where writes should go through approval
readonlySearch, summarization, reporting, and read-only assistants
await inst.plugins.permissions.setMode("slack", "strict");

​
Endpoint overrides

Use overrides when a single operation needs a fixed policy regardless of the plugin’s mode. 
await inst.plugins.permissions.setOverride(
  "github",
  "api.repositories.delete",
  "deny",
);

await inst.plugins.permissions.setOverride(
  "slack",
  "api.channels.list",
  "allow",
);
Supported policies:
PolicyMeaning
allowExecute without approval
require_approvalPause and require approval before execution
denyBlock execution
Remove an override to return the endpoint to the plugin mode: 
await inst.plugins.permissions.deleteOverride(
  "github",
  "api.repositories.delete",
);
Fetch current permissions: 
const permissions = await inst.plugins.permissions.get("slack");

console.log(permissions.mode);
console.log(permissions.overrides);

​
Shared credentials

Root credentials are shared at the instance level. They are commonly used for OAuth app configuration, such as client_id, client_secret, and redirect_url. 
await inst.plugins.credentials.setRoot("github", "client_id", "Iv1...");
await inst.plugins.credentials.setRoot("github", "client_secret", "...");
await inst.plugins.credentials.setRoot(
  "github",
  "redirect_url",
  "https://app.example.com/oauth/callback",
);
Clear a root credential during rotation: 
await inst.plugins.credentials.clearRoot("github", "client_secret");
Inspect configured fields without returning raw secrets: 
const { fields } = await inst.plugins.credentials.list("github");

for (const field of fields) {
  console.log(field.field, field.scope, field.set, field.preview);
}
The field argument is typed per plugin. setRoot("github", ...) autocompletes GitHub’s root fields, while setRoot("gmail", ...) includes Gmail-specific fields such as topic_id.

​
Plugin catalog

Build plugin picker UIs from the hosted catalog: 
const { plugins } = await corsair.catalog.plugins.list();

const oauthPlugins = plugins.filter((plugin) => plugin.supportsManagedOAuth);
For static compile-time data, import the generated catalog: 
import { PLUGINS, PLUGINS_BY_ID } from "@corsair-dev/app";

console.log(PLUGINS_BY_ID.slack.displayName);

​
Runtime refresh and health

Corsair refreshes runtime state as you change plugins and credentials. You can force a refresh after setup or check whether the runtime is warm. 
await inst.runtime.refresh();

const status = await inst.runtime.status();

console.log(status.warm);
console.log(status.dbOk);
Plugin mutation responses include runtimeRefreshed when the hosted runtime has already picked up the change.

​
Remove a plugin

await inst.plugins.delete("slack");
Removing a plugin prevents it from being callable through MCP or tenant.run(). Tenant credentials for that plugin are not deleted automatically.