Gini Agent: a headed browser on purpose, secrets kept out of the model and typed into it
The agent that remembers and learns.
At a glance
- What is it?
- Gini is a personal agent that runs as a single Bun process per instance, with a web control plane, a command line tool, a mobile app and messaging bridges all speaking one authenticated contract. Reading its container and package files closely shows the browser deliberately run headed under a virtual display so it presents fewer automation signals, the browser sandbox switched off in that same configuration, four packages trusted to run install scripts, a local patch applied to the browser driver itself, and a primary test command that does not cover the web package.
- Who is it for?
- Gini Agent suits one person who wants an agent with persistent memory that can act on their behalf across their own accounts, with a consent step in front of anything sent and a way to unblock a sign-in from a phone.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 120 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- Open-Curiosity/gini-agent2,398 ★ · +295
| Repository | 2026-09-10 | 2026-11-15 |
|---|---|---|
| Open-Curiosity/gini-agent | 2.1k | 2.4k |
295 Stars in the last 66 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The container runs a headed browser on purpose, to look less automated
The most consequential sentence in this repository is in the container file, and it is a design decision rather than an accident. The image runs the runtime and the web control plane together with a real, headed Chromium driven by the browser automation library, under a virtual X display rather than a null one. The file explains why in plain terms: headed under a virtual display is deliberate, because a real Chrome presents far fewer automation signals than the newer headless mode, and this complements what the file calls a stealth identity, citing two decision records by name, one of them a browser stealth identity record. So the project is explicit that one of its choices exists to reduce how much the browser looks like a robot. That is a different goal from the user-facing one the readme describes, which is legitimate and well specified: when a task hits a sign-in wall, the agent hands you a live view of its own browser so you can complete the step yourself, and it resumes where it left off. You are signing into your own accounts. The automation signals are for the sites that inspect the browser before serving you a sign-in form at all, and that is a general capability rather than a per-site one.
Secrets are kept out of the model, then typed into a browser with the sandbox off
The readme's strongest security claim is specific and worth quoting in substance: a key, password, one-time code or payment field is typed into a secure card that flows straight to the gateway and never reaches the model, the transcript, or the audit trail. That is a well-drawn boundary, because it removes credentials from three places they commonly leak, including the log a human might paste into a bug report. The same section then explains that the agent can hand you its own browser to finish a step it cannot, and the decision records it links are named for filling a secret into a browser and for provisioning credentials through the chat. Read together, the two statements describe credentials being kept out of the model's context and out of the audit trail, and simultaneously being routed into a browser process. In the container that browser is launched with its sandbox disabled: the compose file sets a no-sandbox flag to one, and its comment refers to the image carrying a shared-memory workaround switch that comes from the same family of flags. Every individual choice here is written down and reasoned. The trust surface they add up to is the thing to weigh.
The one-line install registers two launch agents and opens a browser
The quick start is a single line:
curl -fsSL https://raw.githubusercontent.com/Open-Curiosity/gini-agent/main/scripts/install.sh | bashThe behaviour behind it is more than installing software. The text says that on macOS the installer enables autostart through per-user launch agents for the runtime and for the web app, waits for the web app to come up, and opens the setup page in the browser. So the documented happy path fetches a script from the default branch, registers two persistence entries that will relaunch the services after a reboot, starts a web server, and hands you a browser window. None of that is unreasonable for a personal agent you are meant to leave running, and all of it is exactly what you would want to know before running it. There is a non-script route in the operations document, which covers install, start, stop, a smoke check, diagnostics and cleanup. The practical advice is to read the script before piping it, particularly because the address points at the default branch rather than at a tag, so the script you run today is whatever that branch holds today.
The browser driver is pinned, locally patched, and its dependencies are trusted
The package manifest contains three lists that together describe the trust surface. The first names four packages as trusted to run their own install scripts: a native inference runtime, a native image library, a protobuf implementation and a native module resolver. Allowing install scripts is normally a supply-chain decision you make per dependency, and the inference runtime is the one that matters most here, because it is what backs the local embeddings and reranking the readme lists as on by default. The second list declares a local patch, applied to one exact version of the browser automation library, with a patch file in the repository. So the browser driver is not the upstream artefact; it is the upstream artefact plus a modification this project maintains. The third is a version catalogue shared across the workspace, which pins the type checker to a patch range inside version six, the query library to a major-minor caret and the runtime type definitions to a caret. Each of these is a reasonable, narrow decision. Together they are the list of places where what you get is not simply what upstream published, and that is the list to read. One more decision belongs with them, and it is a good one. The runtime is a single process per instance that owns state and performs all the work, and every surface is a client of the same authenticated contract:
GATEWAY (Bun runtime, one per instance)
state, agent loop, tools, memory, jobs
^
--------------------+--------------------
| | |
Next.js BFF CLI / scripts other clients
browser UI bearer token mobile, MCP, messaging
no browser tokenThe last two lines are the point. The browser interface never holds a bearer token; the server-side layer in front of it does, and the command line and scripts authenticate with a token directly. Putting the credential in the server-side tier rather than in the page is the difference between a token that can be read from a view-source panel and one that cannot. The same diagram also explains the parallel-instances feature: state, ports and logs are isolated per instance, so a second instance is a second runtime process rather than a namespace inside the first.
The primary test command does not cover the web package
The manifest wires tests in two steps and the first step is the one you would run. The test script invokes the runner against four paths in parallel: the runtime source, the skills directory, the mobile source and the mobile plugins. The web package is not in that list. It is tested by a separate hook that runs after the first script finishes, in its own package directory, with isolation between tests so they cannot see each other's state. The arrangement is defensible, since the web package has a different toolchain and isolating it avoids cross-contamination. The problem is discoverability. Running the obvious command on this repository does not run the web tests, and a green result from it means the runtime, the skills and both mobile trees passed and the web package was never asked. The skills directory being a first-class test target is the more interesting half: the agent's skills are treated as a unit with its own assertions, which fits a project whose headline claim is that the agent improves its own skills.
The container's default provider is a stub that echoes
The compose file picks a provider from the environment with a fallback, and the fallback is the word echo, annotated as a deterministic stub. Every real provider variable below it is commented out, including the keys, the model name and the other credentials. The practical effect is that a container started with no configuration boots into a working system that does not talk to any model, which is the right default for a project that installs an agent that can spend money and act on your accounts: nothing happens until you supply a credential. The readme also states that the provider can be configured after boot at the setup page, so the two defaults complement rather than conflict. The supported catalogue is eight entries wide and the two paths through it are deliberately different in kind: one is an OAuth flow for a coding assistant, four take ordinary API keys including a cloud-hosted variant of one of them, one is a first-party key, one is a signed-request interface that covers several model families from one vendor, and the last is any server speaking the common wire format, which covers local models. Local embeddings, reranking and speech-to-text are on by default with no provider involved.
The readme is an index of fifteen documents and never says what the name means
The page itself runs to about nine hundred words and is almost entirely a table of contents, with links to roughly twenty-five separate documents. There is a whitepaper, an architecture overview, a gateway and control plane description, a conversation and runs document, a memory document, a skill-learning document, a runtime capabilities map with verification commands, per-provider setup guides, an operations runbook, a container deployment guide, a remote access document with four separate tunnel guides behind it, a releases document, a migration guide for moving from a different agent install, implementation notes on source layout and module boundaries, a roadmap, and an index of architecture decision records explaining how to add new ones. That is an unusually complete documentation posture for a project at version zero point three, and it means the readme's job is routing rather than teaching. What the readme never does is say what the name means. The project is called after a four-letter word that is also a well-known term in decision trees, and neither the page nor the documents it indexes expand it. If the name has an origin worth knowing, it is not written down.
The claim that does get a mechanism is the one in the project's description, that the agent remembers and learns. That has its own document, which names four parts rather than asserting the effect: a two-tier reward, attribution, a daily review, and a human gate. Read together those four are a fairly demanding design for a personal tool. A two-tier reward means outcomes are scored at more than one level of the task rather than by a single pass or fail. Attribution means the system works out which step in a multi-step run deserves the credit or the blame, which is the hard part of learning from trajectories. A daily review means improvement is batched on a schedule rather than applied mid-task, so a bad run does not immediately change behaviour. And a human gate means the agent proposes changes to its own skills and waits for you. So the learning loop is explicitly bounded by a person, which is the part worth knowing before you install something that edits its own instructions.
Shared memory is raised to a gigabyte because the default crashes the renderer
The compose file carries one of the better comments in the batch, and it is worth reading for the shape of the reasoning rather than the setting. Chromium uses shared memory, the container default of sixty-four megabytes is too small, and the result is renderer processes dying with a target-closed error. There are two ways out: raise the shared memory allocation, or pass a launch switch that makes the browser ignore shared memory limits instead. The file says raising it is the better performing path and then does both anyway, keeping the launch switch as a fallback. That is the pattern to notice across this repository. The same belt-and-suspenders logic appears on the init flag, kept in the compose file even though a proper init process is already baked into the image entrypoint, with the reason given. The image pins its base to an exact runtime version and ties that pin to the lockfile's toolchain, installs the browser's shared libraries under the suffixed names the current Debian release requires, adds a threading runtime because the slim base omits it, and installs a font set so pages render glyphs instead of empty boxes.
Editorial conclusion
Gini Agent suits one person who wants an agent with persistent memory that can act on their behalf across their own accounts, with a consent step in front of anything sent and a way to unblock a sign-in from a phone. It does not suit anyone who wants a readable agent implementation, because the product is fifteen documents and a runtime you are meant to operate rather than read, and it does not suit an environment where a patched browser running without a sandbox holds live sessions is unacceptable. Before you install it, read the install script rather than piping it, because the documented one-line route registers two launch agents and opens a browser. If you enable the browser, know that the sandbox is off, the driver is locally patched, and the design intent recorded in the project's own decision records is to look less like automation. And check what your test run actually covered, because the obvious test command skips the web package.
Frequently asked questions
What does Gini stand for?
The repository never says. The readme, the whitepaper and the documents it indexes all refer to the project as Gini or Gini Agent without expanding the name, and the description is the single line about an agent that remembers and learns. The four-letter word is also a common term in decision trees, which is a coincidence the documentation does not address.
How do I install Gini Agent?
The quick start pipes an install script fetched from the repository's default branch into a shell. On macOS that script enables autostart through per-user launch agents for the runtime and the web app, waits for the web app and opens the setup page in your browser. An operations document covers the non-script route: install, start, stop, smoke, diagnostics and cleanup.
Does Gini Agent send my credentials to the model?
The readme says a key, password, one-time code or payment field is typed into a secure card that goes straight to the gateway and never reaches the model, the transcript or the audit trail. It also describes the agent handing you a live view of its own browser to complete a sign-in or sensitive step, so credentials are routed into a browser process, which in the container image runs with its sandbox disabled.
Which AI providers does Gini Agent support?
Eight routes are documented: an OAuth flow for a coding assistant, API keys for a hosted provider, a cloud-hosted variant of it, two more keyed providers, a first-party vendor key, a signed-request interface covering several model families from one vendor, and any server speaking the common wire format for local models. The provider documentation index lists them as credential and prerequisite guides per provider.
How does Gini Agent's test suite cover the web app?
It does not, in the primary command. The test script runs against the runtime source, the skills directory, the mobile source and the mobile plugins. The web package is tested by a separate hook that runs afterwards in its own package directory with isolation between tests, so running the obvious test command leaves the web package untested.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/open-curiosity-gini-agent)Star history chart for your README
[](https://hysenlabs.com/projects/open-curiosity-gini-agent)Was this useful?