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 securely 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 secure shell (SSH) session. Now, install any packages, libraries, or system dependencies your agent needs (e.g., custom database drivers, compilers, or CLI tools):

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

Note the created Session ID (e.g. ses_abc123) from the command output. Since you passed --keep, the session remains in a paused state after you exit, ready to be promoted.

Save this exact environment state as a reusable template. Give it a descriptive name (e.g. data-science):

# Save the session state as a template
inis templates save ses_abc123 --name data-science --description "Python + Pandas + Graphviz environment"

The template is now stored durably in your account. Any new sessions created with the data-science template will instantly restore from this exact baseline in under 50ms.

In your TypeScript backend, use the @inis/client SDK to create sessions using your custom template, and retrieve the session-scoped MCP URL:

import { Client } from "inis";

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

// 1. Create a session from your custom template
const session = await client.sessions.create({
  template: "data-science",
});

// 2. Hand the session's MCP URL and authorization header to your agent harness
// The agent now has direct, secure tool access to the data-science environment.
await agent.connect({
  mcpUrl: session.mcpUrl,
  headers: {
    Authorization: `Bearer ${process.env.INIS_API_KEY}`,
  },
});

To avoid paying for idle compute when the agent is waiting on model responses, you can pause the session:

// Pause the session (snapshots memory state to disk and stops billing)
await session.pause();

When the agent receives a new message and invokes an MCP tool, the session-scoped MCP gateway automatically wakes up the session transparently (restoring state in ~50ms), handles the execution, and keeps running. This ensures you only pay for active execution seconds.