Integrating Claude Agent SDK with Shellify via Tool Calls

Introduction

AI agents like Claude can greatly benefit from the ability to execute shell commands in controlled environments — for tasks such as running tests, building artifacts, or inspecting files created during a workflow. ShellifyAI provides secure, sandboxed shell execution for this use case. This guide shows how to integrate the Claude Agent SDK (or any agent framework that supports tool calls) with Shellify by forwarding tool invocations to Shellify’s execute API.

What you’ll learn

The integration patterns for handling tool calls from Claude-style agents
How to forward tool calls to the Shellify API (POST https://shellifyai.com/v1/execute)
Best practices for sessions, streaming output, and security
Example code snippets you can adapt to your agent runtime

Prerequisites

A Shellify project and API key (SHELLIFYAI_API_KEY) from the Shellify console
A Claude Agent SDK project or an agent runtime that can define tools and handle tool invocations

Why use Shellify for agent tools?

Shellify handles sandboxing, session persistence, timeouts, streaming stdout/stderr, and file artifact capture. Instead of giving an agent direct access to your host, forward commands to Shellify and let it manage isolation and security policies.

High-level integration patterns

In-process tool handler If your agent runtime exposes a programmatic hook for tool calls (for example, a function invoked when a tool is requested), call Shellify directly from that handler and return the result back to the agent.
Webhook (HTTP) handler If your agent runtime can be configured to send tool invocations to an HTTP endpoint, implement a small webhook that forwards the payload to Shellify and returns results.

Both approaches share the same core behavior: when the agent decides to run a shell command, your code forwards the request to Shellify's POST https://shellifyai.com/v1/execute endpoint and returns the execution events to the agent as the tool result.

Required Shellify request basics

Every execution uses the same API endpoint. Include your project API key in the x-api-key header and post a payload describing the command and options.

Endpoint: POST https://shellifyai.com/v1/execute

Minimum request body (JSON):

adapterType (optional) — override the project default (for Claude use: "claude_agent")
tool — "local_shell"
payload.command — the shell command to execute

Environment variables (required): SHELLIFYAI_API_KEY=your_api_key

Forwarding a tool call (minimal example)

Below is a minimal server-side example that forwards an incoming tool invocation to Shellify and returns the result. This is intentionally generic so it can be adapted to your Claude Agent SDK integration point.

JavaScript (node-fetch / fetch):

javascript
1const forwardToShellify = async ({ command, sessionId, sdkLanguage }) => {
2  const res = await fetch(
3    `https://shellifyai.com/v1/execute`,
4    {
5      method: 'POST',
6      headers: {
7        'Content-Type': 'application/json',
8        'x-api-key': process.env.SHELLIFYAI_API_KEY
9      },
10      body: JSON.stringify({
11        adapterType: 'claude_agent', // explicitly choose the Claude adapter (optional)
12        tool: 'local_shell',
13        payload: {
14          command,
15          sessionId,
16          sdkLanguage // for Claude: 'python' or 'typescript' if relevant else leave empty it will use python
17        }
18      })
19    }
20  );
21
22  return res.json();
23};

If your tool handler receives a call object with the command and a call id, call this function and attach the returned execution result back to the agent according to the agent SDK’s tool-result API.

Handling streaming output

Shellify supports streaming responses (application/jsonl) for real-time stdout/stderr updates. If you want to stream logs back to your chat UI or agent loop, request a streaming response and relay lines as they arrive.

To enable streaming:

Set the Accept header to application/jsonl OR
Append ?stream=true to the request URL

Each line in the response is a JSON object with types like meta, status, log, artifact, and completed. Relay these to the agent or to a frontend UI so users can see the command progress.

Example: fetch streaming relay (Node)

javascript
1const relayStreaming = async (req, res, { command }) => {
2  const fetchRes = await fetch(
3    `https://shellifyai.com/v1/execute?stream=true`,
4    {
5      method: 'POST',
6      headers: {
7        'Content-Type': 'application/json',
8        'x-api-key': process.env.SHELLIFYAI_API_KEY,
9        'Accept': 'application/jsonl'
10      },
11      body: JSON.stringify({
12        adapterType: 'claude_agent',
13        tool: 'local_shell',
14        payload: { command }
15      })
16    }
17  );
18
19  const reader = fetchRes.body.getReader();
20  const decoder = new TextDecoder();
21  let buffer = '';
22
23  while (true) {
24    const { done, value } = await reader.read();
25    if (done) break;
26    buffer += decoder.decode(value, { stream: true });
27
28    let lines = buffer.split('\n');
29    buffer = lines.pop();
30
31    for (const line of lines) {
32      if (!line.trim()) continue;
33      const obj = JSON.parse(line);
34      // obj.type === 'log' -> obj.data, stream: 'stdout' or 'stderr'
35      // relay obj to your agent or UI
36      console.log('stream event', obj);
37    }
38  }
39
40  if (buffer.trim()) {
41    const last = JSON.parse(buffer);
42    console.log('final event', last);
43  }
44};

Session persistence across multiple tool calls

If your agent workflow requires multiple related commands (for example: create files, run tests, collect outputs), use Shellify sessions. Provide sessionId in the payload to reuse the execution environment and retain generated files between calls.

payload.sessionId: a string you control (e.g., a UUID per chat or per task)

Example payload with session:

json
1{
2  "adapterType": "claude_agent",
3  "tool": "local_shell",
4  "payload": {
5    "command": "pytest -q",
6    "sessionId": "conversation-1234"
7  }
8}

Artifacts and file capture

Shellify automatically captures files created during execution and uploads them as artifacts with signed URLs. The streaming event type artifact includes filename and url. Provide sessionId when you need to keep files across multiple steps; otherwise artifacts are still captured per execution and available in the response events.

Choosing sdkLanguage for Claude

If your integration involves generating or executing code produced by the Claude agent, set payload.sdkLanguage to hint Shellify for adapter behavior. Supported values: "python" or "typescript". This is optional but useful when the agent produces multi-file projects and you want the sandbox behavior tailored to the language.

Security best practices

Never allow arbitrary long-running commands; set timeoutMs when appropriate (default: 120000 ms)
Use sessions for controlled persistence and delete or rotate session IDs as needed
Do not expose SHELLIFYAI_API_KEY to the browser; keep the key on your backend
Always rely on Shellify’s sandboxing; commands forwarded to Shellify run in isolated containers
If you implement custom system messages, be aware that Shellify always appends its security policy to systemMessage

Putting it together: sample webhook flow

Claude Agent SDK issues a tool call to your configured tool handler (either in-process or via webhook).
Your handler extracts the command, optional sessionId, and any metadata.
Forward the call to Shellify using POST https://shellifyai.com/v1/execute with adapterType: "claude_agent".
Optionally stream the response back to your UI or pass the final result to the agent as the tool output.

Troubleshooting tips

If you see permission or network errors, verify the x-api-key header is set and correct
For incomplete outputs, try streaming mode to see detailed logs
If files are missing, ensure you used a sessionId when you expected persistence across runs
Use timeoutMs to avoid hung executions and to enforce resource limits

Conclusion

Integrating the Claude Agent SDK with Shellify is a matter of forwarding the agent’s tool invocations to Shellify’s execute API and returning results. Whether you handle tool calls in-process or via webhooks, Shellify provides a secure sandbox, streaming logs, file artifacts, and session persistence to support complex multi-step agent workflows. Use adapterType: "claude_agent" and payload.sdkLanguage when relevant to make the adapter behavior explicit.

Next steps

Create a Shellify project and get your SHELLIFYAI_API_KEY from the Shellify console
Implement a small tool handler in your Claude Agent runtime that forwards calls to Shellify
Start with non-streaming calls to validate correctness, then add streaming for real-time feedback

Resources

For full API reference and developer documentation, see https://shellifyai.com/docs