Ownbox SDK

Custom machines

Add your own features to an Ownbox. A custom machine is a small Python program that a developer writes, the owner approves, and the Ownbox runs safely in a locked space of its own.

Python SDK version 1

Markdown

What is a custom machine?

A custom machine gives an Ownbox one new job. It can be a page on the dashboard, a task that runs on a schedule, a part of the owner's Morning Review, or a question the owner's AI can answer.

It is a small folder of Python, written on the developer's own computer. The developer keeps the code: in a folder, or in their own git repository if they use one. The Ownbox never connects to GitHub or any repository. It receives the files, checks them, tests them, and installs them only after the owner says yes. Once installed, the machine runs in a locked space of its own and can do only what the owner approved.

Who it is for: developers and agencies building for a business that runs on an Ownbox, and the owner who decides what runs on it.

What a machine can do

Run tasks on a schedule, from every 15 seconds to once a week.
Show its own pages on the dashboard, and a card on the Inbox screen.
Add its part to the owner's Morning Review.
Answer questions from the owner's AI.
Ask the owner to approve an action, and carry it out after a yes.
Use the Ownbox's AI, within a monthly allowance.
Reach websites and services the owner allowed, with API keys the Ownbox adds for it.
Read and add to the business's people and inbox, and send messages and emails within a daily limit.
Keep its own settings and its own database.

What a machine cannot do

Connect to the internet on its own. The Ownbox makes every request for it, only to the websites the owner approved.
See a password or an API key.
Read the Ownbox's files or its database. It reads people and conversations through named calls only.
Do anything the owner did not approve. Everything else is refused, with the reason.
Install code the owner did not see. What installs is exactly what was on the review card.

Can I bring an existing app?

You can bring the app's logic, not its framework. A machine is Python that the Ownbox runs and draws pages for. It has no web server, port, front end or network connection of its own. The pattern that works: your app keeps running where it runs today, and the machine is the bridge between it and the Ownbox.

Fits in a machine	Does not fit
Python and its standard library, plus packages from the Ownbox's list (numpy, pandas, openpyxl and others)	A web framework, its own server or port, JavaScript, images
Calling your own app or any service over https, to websites the owner allowed	Its own network connection, or an API key it can read
Pages drawn by the Ownbox from simple blocks: text, figures, lists, tables, buttons, settings	Forms of its own: its one form is a settings block the Ownbox saves
Its own SQLite database in its own folder	The Ownbox's own database
The Ownbox's AI, within a monthly allowance	Calling an AI company directly
Scheduled tasks, approvals, a Morning Review part, answers for the owner's AI	Heavy work: it has 256 MB of memory and half a CPU core, or up to 1 GB and two cores on an Ownbox with the memory

An example. An agency's scheduling app stays on its own servers. Its machine checks for new bookings every hour, adds each customer to the Ownbox, asks the owner before sending a follow-up, and shows a Bookings page.

How it works, step by step

Nothing is installed until the last step, and the owner says yes twice: once to test it, and once to install it.

Write it on your computer. One line installs the kit, the ownbox command, with nothing else installed first: curl -fsSL https://www.ownbox.io/install.sh | sh in Terminal on a Mac or Linux, or irm https://www.ownbox.io/install.ps1 | iex in PowerShell on Windows. Then ownbox new my-machine writes a starter machine, and ownbox example lists complete examples to copy instead.
Try it on your computer. ownbox run my-machine runs it once against a local Ownbox with sample data, and shows what it would have done. ownbox preview my-machine opens its pages in your browser, drawn as the Ownbox draws them. Nothing leaves your computer.
Connect Claude to the Ownbox, once. The owner's Developers page shows the one line to run, with the Ownbox's own address. It signs in as the owner, so the owner gives it only to a developer they trust.
Send it. Ask Claude to send the machine. It sends the files to the Ownbox, which asks the owner on Approvals.
The Ownbox checks and tests it. After the owner's yes, the Ownbox checks the files, then runs the machine twice as a test. The first run uses the owner's real data and sends nothing. The second reaches only the websites the owner picks for the test, using a made-up sample business.
The owner approves it. The review card lists every permission in plain words, what it installs, and how the tests went. The owner taps Approve.
It installs and runs. The Ownbox installs exactly the code on the card. The machine appears in the menu, and its page opens at /my/<its-name>.

The owner can also describe a machine in a sentence on the Developers page, and the Ownbox's own AI writes it, tests it and brings it to the same review card.

How it stays safe

Protection	What it means
A locked space of its own	Each machine runs as its own user, never as the administrator, with no way to gain more rights.
No internet of its own	Every web request is made by the Ownbox, only to the websites the owner approved.
Keys stay hidden	The Ownbox adds an API key to a request for that key's own website. The machine never sees it.
Only its own files	It sees its own code, read-only, and writes only in its own folder. The Ownbox's files are out of reach.
Only what was approved	Every permission is a line on the review card. Anything else is refused.
Limits it cannot raise	256 MB of memory and half a CPU core, or the bigger size it asked for and the owner approved, a daily limit on messages, a monthly limit on AI use. It spends money on a service only within a monthly limit the owner sets.
What installs is what was seen	The approved code is sealed and fingerprinted, and checked again as it installs.
The owner stays in control	Roll it back to the version before, or remove it. Its data stays on the Ownbox.

After it is installed

When it runs. The Ownbox starts it when it has something to do: a task is due, someone opens its page, the owner's AI asks it something, or an approval comes back. It stops after 5 idle minutes. After a crash it waits before starting again, a little longer each time.
Where it shows up. Its own page and its row in the menu, a card on the Inbox screen, its part of the Morning Review, answers for the owner's AI, and its requests on Approvals.
New versions. The developer sends the next version the same way, with a higher version number. The owner approves it on a new review card, and it replaces the old one, which is kept for a rollback.
Rolling back. After 4 failures in a row, its page offers the version before.
Removing it. The owner types its name to remove it. Its data is kept on the Ownbox.

Demo Ownboxes

On a demo Ownbox lent to a partner, the partner builds and tests freely, but nothing installs until Ownbox has read the code.

The partner taps Approve. The Ownbox sends the sealed code to Ownbox, and the card says it is waiting for Ownbox.
Ownbox reviews that exact code and answers yes, or no with the reason.
The Ownbox picks up the answer at its next check-in. A yes installs that code and nothing else. A no shows Ownbox's reason on the card.

Nobody, the partner included, has server access to a demo Ownbox.

What is live and what is coming

Live today

Sending a machine from Claude: approval, checks, test runs, review card, install.
Describing a machine to the Ownbox's own AI (not on demo Ownboxes lent to partners).
Ownbox's review before anything installs on a demo Ownbox.
The ownbox kit: new, run and example.
Packages from the Ownbox's list.
Sending a new version of an installed machine, reviewed again before it replaces the old one.
Claude resending fixed files to a build the check refused, with the owner's yes.
Rolling back and removing.

Coming

Erasing a person on the Ownbox reaching the machine's own data. A machine that keeps people already defines how it forgets one; the Ownbox does not ask it yet.
A machine's own menu items and Activity log lines.
One machine installed on many Ownboxes from a catalog.

Where to next

Build a custom machine: the developer's guide: the rules, the manifest, permissions, pages, the lifecycle, limits and errors.
The SDK reference: every call a machine can make, with an example that runs.