# Run TinyFish web agents from a Tenki Sandbox (https://tenki.cloud/blog/tinyfish-tenki-sandbox) > For the complete documentation index, see [llms.txt](https://tenki.cloud/llms.txt) - Author: Guzman Pintos (Product) - Published: Oct 27, 2026 - Category: [Sandbox](https://tenki.cloud/blog/category/sandbox) - Reading time: 5 min A pre-built Tenki image with the TinyFish CLI, SDK and Playwright client. Run web agents, fetch, search and remote browsers from an isolated VM. Tenki now publishes a [TinyFish](https://docs.tinyfish.ai/) image. Start a sandbox from `tenki/tinyfish:stable` and the VM boots with the TinyFish CLI, the `@tiny-fish/sdk` TypeScript SDK and `playwright-core` already installed. Add your TinyFish API key when you create the session, and your agent can browse, fetch and search the web from its own isolated Linux machine. ## What TinyFish does TinyFish runs web automation for agents behind four APIs, and the image ships a client for each: * **Agent:** give it a URL and a goal in plain English, and TinyFish's agent browses the page and returns JSON. Pass a JSON Schema to fix the shape of the answer. There are no selectors to write or keep up to date. * **Browser:** a remote Chromium session with a Chrome DevTools Protocol (CDP) URL you drive from Playwright. * **Fetch:** up to 10 URLs per call, returned as markdown, HTML or JSON. * **Search:** web search results, with optional location and language. TinyFish also offers [Research](https://docs.tinyfish.ai/research-api), which turns a question into a cited report, and [Monitor](https://docs.tinyfish.ai/monitor), which re-checks a page on a schedule and reports what changed. If you only want these tools inside Claude Code or Cursor, without a sandbox, TinyFish's hosted [MCP server](https://docs.tinyfish.ai/mcp-integration) does that. The agent API is the one that changes how you build. Instead of writing a Playwright script for each site and fixing it when the markup changes, your code asks for the data it wants and gets structured output back. ## How the work splits Your code runs in the [Tenki Sandbox](https://tenki.cloud/products/sandbox): an isolated sandbox with its own filesystem, processes and network, billed per second while it runs. The browsers and agents run at TinyFish. The image has no local browser and no API key baked in; the CLI and SDK read `TINYFISH_API_KEY` from the session environment. That split has two consequences. Every page action is a network round trip from the VM to TinyFish, so a script that polls the DOM in a tight loop is slower than it would be against a local browser. And a TinyFish browser can't reach a dev server on `localhost` inside your VM. For the sites your agent actually visits on the public web, neither tends to matter. ## Try it in two commands [Sign up for TinyFish](https://agent.tinyfish.ai/sign-up) and create an [API key](https://agent.tinyfish.ai/api-keys), then start a session with it: ```bash export TINYFISH_API_KEY= tenki sandbox create \ --image tenki/tinyfish:stable \ --env "TINYFISH_API_KEY=$TINYFISH_API_KEY" \ --name tinyfish-demo tenki sandbox exec --session tinyfish-demo -- tinyfish-smoke https://example.com ``` `tinyfish-smoke` exercises all three clients against one remote browser: the SDK opens the session, Playwright loads the page over CDP, and the CLI closes it. A working setup prints the page title: ```json { "session_id": "tf-...", "url": "https://example.com/", "title": "Example Domain" } ``` From there, the CLI covers the other APIs. This runs an agent against Hacker News and waits for the answer: ```bash tenki sandbox exec --session tinyfish-demo -- \ tinyfish agent run "Return the title and points of the top 5 stories as JSON." \ --url https://news.ycombinator.com --sync ``` `tinyfish fetch content get --format markdown` and `tinyfish search query ""` work the same way. Every command prints JSON, which is what an agent calling the CLI wants to read. Terminate the session when you're done: ```bash tenki sandbox terminate tinyfish-demo ``` ## Use it from your own code Because the SDK and `playwright-core` live under `/home/tenki/node_modules`, any script below `/home/tenki` can import them without another install. The one thing to get right is closing the remote browser. TinyFish bills a browser session until it is closed or reaches its idle timeout, so set `timeout_seconds` low and close the session in a `finally` block. The SDK has no close method, so that means a `DELETE` to TinyFish's session endpoint. The [TinyFish docs page](https://tenki.cloud/docs/sandbox/tinyfish.md#use-the-sdk-and-playwright-in-your-code) has the full script. The Python SDK isn't preinstalled. `pip install tinyfish` inside the session if you'd rather write Python. ## Keep the key at session scope Pass `TINYFISH_API_KEY` with `--env` when you create the session, and nowhere else. A key baked into an image or a template reaches every session started from it. Snapshots drop the session environment, but a process still running when you snapshot keeps the key in memory, so stop it first. Keep the session short, terminate it when the work is done, and rotate the key in TinyFish if you think it leaked. The `tinyfish` command defaults `TINYFISH_NO_TELEMETRY` to `1`, which turns off the CLI's analytics and update check. Set it to `0` in the session environment if you want them back. ## Pin the build you tested `tenki/tinyfish:stable` moves to each new build. For an agent you've tested and deployed, resolve the tag once and launch the snapshot it points to: ```bash tenki sandbox registry resolve tenki/tinyfish:stable tenki sandbox create --image tenki/tinyfish@ ``` A snapshot reference never moves, so the CLI and SDK versions under your agent only change when you choose to move. ## Get started The [TinyFish docs page](https://tenki.cloud/docs/sandbox/tinyfish.md) walks through the session, the CLI, the SDK and pinning. If you're new to Tenki, the [sandbox quickstart](https://tenki.cloud/docs/sandbox/quickstart.md) takes you from install to a running VM.