Custom Agent Templates & MCP

Guide on setting up a custom sandbox environment, building a template, and connecting your agent via MCP.

This guide walks through creating a customized execution environment for your AI agents. You will set up the environment interactively using the CLI, save it as a reusable template, spawn sessions from it in your TypeScript backend, and connect your agent using the session-scoped MCP server.

First, spin up a base session using the inis CLI, asking it to keep the session alive when you exit:

# Create a fresh session and enter it interactively
inis ssh --keep

This boots a clean sandbox and drops you into a shell. Install packages and system dependencies your agent needs:

# (Inside the sandbox)
pip install pandas scikit-learn
sudo apt-get update && sudo apt-get install -y graphviz
exit

Note the Session ID from the command output. With --keep, the default on-detach policy pauses the session after you exit so you can save it as a template.

Save this environment as a reusable template:

inis templates save 9hmquuxiz7qyqdqiwfvep --name data-science --description "Python + Pandas + Graphviz environment"

New sessions created with the data-science template start from that baseline. See Templates.

Use the @inis-run/sdk TypeScript SDK to create a session from your template, then hand the SSE MCP URL to your agent:

import { Client } from "@inis-run/sdk";

const client = new Client({ token: process.env.INIS_API_KEY });

const session = await client.sessions.create({
  template: "data-science",
});

// mcp_url from the API is the session base — clients need the /sse path
const { mcpUrl } = await session.get();
const sseUrl = mcpUrl.endsWith("/sse") ? mcpUrl : `${mcpUrl}/sse`;

await agent.connect({
  mcpUrl: sseUrl,
  headers: {
    Authorization: `Bearer ${process.env.INIS_API_KEY}`,
  },
});

Session MCP tools operate on this session (run_command, files, expose, checkpoints, …). See Remote MCP → Session MCP for the full tool list and limits.

To avoid paying for idle compute while the model thinks:

await session.pause();

When the agent next calls a session tool (run_command, files, expose, …), the API resumes the session automatically (wake-on-op). Resume speed depends on whether the paused session is still hot/warm or has gone cold — see Session lifecycle.