Jelly / Getting started

Get Jelly running

Jelly connects an AI assistant to a real Chromium browser. This guide walks you through installing it on Linux, choosing a browser, connecting an AI client, and checking that it works.

One real setup command: ./scripts/dev.sh. It asks before saving settings, creating a browser container, or installing services.

Jump to: Requirements · Start setup · Browser choices · AI connection · Check it works · First AI prompt · Get help

1. What you need

Use a Linux computer with:

Git to download Jelly and Rust 1.98.1 with Cargo to build it.
Bash, standard command-line utilities, and a working systemd --user service manager.
One way to run Chromium: installed locally at /usr/bin/chromium, an accessible Docker/Podman engine, or an existing reachable Chrome DevTools Protocol (CDP) browser.

You do not need Docker or Podman if you choose native Chromium. If you want to connect ChatGPT over the Internet using a temporary HTTPS address, also install cloudflared. Jelly does not install these prerequisites for you.

See the complete requirements if you need help preparing Linux.

2. Download Jelly and start the real setup

Open a terminal on your Linux machine and enter:

git clone https://github.com/FabioFlorey/jelly.git
cd jelly
./scripts/dev.sh

If you already downloaded Jelly, just open its directory and run ./scripts/dev.sh. This is the real configuration wizard, not a simulation. It checks prerequisites, asks a few questions, and shows what will change before applying it. Run it in an interactive terminal.

Only want to see the experience without changing your computer? Run ./scripts/dev.sh demo instead.

3. Choose where the browser runs

Jelly needs Chromium to visit websites. The first part of setup asks you to choose one option:

Native Chromium: use the browser installed on this Linux machine. Choose this if you already have /usr/bin/chromium and want the simplest local setup.
Docker or Podman: run Chromium in a separate container. Choose this if you want container-managed browser profiles and configurable isolation controls.
Existing CDP browser: connect a Chromium instance you already manage, using its address or WebSocket URL. This is for advanced setups.
Keep existing: reuse your current Jelly browser configuration.

You only need one browser option. The container path offers isolated, shared, or ephemeral profiles; optional Chromium sandbox settings and container restrictions are separate choices. A running container does not itself prove the sandbox is active.

To compare the options and their security limits, see the browser deployment guide. Confirmed browser changes can remain saved even if you cancel later setup steps.

4. Choose how your AI connects to Jelly

The next part of the wizard asks how Jelly should be reached. Pick the option that matches your AI client.

CHATGPT / REMOTE ACCESS

HTTPS with OAuth

Choose quick-tunnel for a temporary public HTTPS address (requires cloudflared). ChatGPT uses the HTTPS MCP URL and an OAuth authorization flow. The tunnel address can change after a restart, so you may need to reconnect.

LOCAL MCP CLIENT

Local HTTP with a token

Choose local hosting for an MCP client on this computer. The default endpoint is http://127.0.0.1:8787/mcp; the client authenticates with your Jelly bearer token.

Important for local-only setup: The repository also enables a ChatGPT remote connection profile by default. If you choose local hosting without a public HTTPS origin, remove that remote profile from config/jelly.toml before starting the services. Otherwise startup validation fails.

Show the exact configuration block to remove for local-only setup

Open config/jelly.toml and delete this block, leaving the generic-mcp connection profile in place:

[[mcp.connections]]
provider = "chatgpt"
method = "remote-http"
auth = "oauth"

If you already started the wizard, you can save settings without installing, make this change, and then run ./scripts/dev.sh install when you are ready.

For permanent public HTTPS hosting and other client-specific instructions, see Connect Jelly to your agent.

5. Review your settings, then start Jelly

Finish the wizard's questions about credentials, hosting, and optional integrations:

Review: Jelly shows a summary with secrets hidden.
Save: confirm writing your settings to the local .env file.
Install and start: confirm the separate prompt to build Jelly and start its user services.

You can say no. If you save without installing, start later with ./scripts/dev.sh install. Your .env file contains secrets: do not commit, copy into bug reports, or share it.

6. Check that Jelly is working

After setup finishes, open another terminal in the Jelly directory and run:

./scripts/dev.sh status
curl --fail --silent --show-error http://127.0.0.1:8787/health
curl --fail --silent --show-error http://127.0.0.1:8787/ready

What success looks like: the MCP service is active, /health responds with "status":"ok", and /ready reports "ready":true. These URLs use Jelly's default local address; use your configured listener if you changed it.

Note: a healthy MCP server does not prove that Chromium is already running or connected. Test a browser operation separately after choosing your client.

Optional: verify the authenticated MCP API from the terminal

On the Jelly host, load the token as data, without displaying it, then ask MCP for its tools:

source ./scripts/lib/config.sh
jelly_load_env
curl --fail --silent --show-error http://127.0.0.1:8787/mcp \
  -H "Authorization: Bearer $JELLY_MCP_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

A successful response includes a list of tools. An HTTP 401 response indicates a credential problem, not a broken installation.

7. Connect your AI and try a browser action

For ChatGPT, add Jelly's HTTPS MCP address (ending in /mcp) to your client and complete OAuth authorization. For a local MCP client, use http://127.0.0.1:8787/mcp and the configured bearer token. Follow the connection guide for client-specific steps.

Your first message to Jelly

Once your AI client is connected, copy this prompt into the AI chat. It checks whether the Jelly MCP tools really respond and discovers the correct browser operations without opening or changing a browser session.

Check my Jelly MCP connection and prepare to use its browser tools.

1. Inspect the tools actually available to you in this chat.
   Do not assume Jelly is connected just because I mentioned it.
2. If browser-schema is available, CALL it with action="capabilities".
   A real successful tool result verifies MCP tool execution.
   If instead individual browser tools are published, report them
   from the tools you can actually access.
3. Identify whether Jelly exposes its small or large tool surface,
   or say "unknown" when you cannot establish this.
4. For later browser tasks, discover operations by intent with
   browser-schema action="search", then inspect their exact input
   contract with action="schema" before using browser-call.
   For a large surface, use the published tool schemas.
5. Do not open, close, navigate, click, type, download, or run any
   routine yet. Ask before testing a real browser session.
6. Report separately:
   - MCP connection: verified or not verified, with evidence.
   - Available Jelly tools and tool surface.
   - Browser/Chromium readiness: NOT TESTED.
   - Next safe step and any connection issue.

Never invent tools, claim a browser is ready from tool discovery,
or ask me to reveal authentication tokens.

What success means: Your assistant names Jelly tools it actually sees and receives a successful discovery response. This tests the MCP connection, not whether Chromium is reachable. Browser readiness requires a separate, explicitly approved browser action.

To try Jelly's browser CLI directly on an idle or dedicated browser, run:

cargo run --quiet --bin agent-run -- open-browser https://example.com
cargo run --quiet --bin agent-run -- read-page

These commands open a web page and read its contents. They can change the active page in a shared browser; avoid running them during another user's workflow. A remote browser must be registered and reachable. See MCP request examples for the equivalent agent-facing flow.

Something didn't work?

Missing tools or Chromium: run ./scripts/dev.sh doctor. For container or external browser modes, use the browser-specific checks instead of requiring host Chromium.
Jelly won't start: run ./scripts/dev.sh status and ./scripts/dev.sh logs. If you chose local hosting, check for the remote HTTPS profile described above.
Health check fails: confirm the service is running and that you are using the configured listener address.
Browser unavailable: check Chromium or container/CDP connectivity. MCP health and browser readiness are separate checks.
ChatGPT can't connect: check the public HTTPS MCP URL, OAuth setup, and whether your temporary tunnel address has changed.

See Troubleshooting or the detailed setup reference.