- tags
- #inherited
- description
- Guides for AI Putty: connect your AI, build and review apps, run and supervise AI agents, keep secrets safe, and sync your notes.
AI Putty Help
Short how-tos, each a few steps. Pick what you want to do; the guides below go deeper.
Guides, one topic each: Projects (Create a project, confirm your email, invite people, and set who can do what with roles and permissions.), Toolbox (Every tool of your project on one page, grouped by what you do, with what your level and role can open.), SystemView (See each feature of your app, what you asked for, and whether it is built and checked. Fix it or describe it from there.), SystemViewPro (The full system view: each feature's spec, design, implementation and tests side by side, for spec-driven development.), Expressions (AI Putty's expression language by example: values, arithmetic, text, logic, lists and every core function.), Messages (Who your AI agents may message, how many messages they may send, what they said, and what happens when one misbehaves.), Thoughts (Your private thought locker: capture ideas by typing or voice, tag and find them, and send them to your AI agent as work.), Focus (A Focus gathers one subject's thoughts and docs on one page, and turns a search into tasks for your AI agents.), Meld (Mind Meld puts your AI agent beside you in AI Putty. Its four levels, Off, Chat, Nudge and Active, and what each lets it do.), Voice (Dictate thoughts and chats, and control them with "ok" commands. How it works in Thoughts and in a chat.), Drafts (See what is waiting to be published, yours and your AI's, compare it, and publish or discard each draft.), Pipeline (The pipeline is the list of work for you and your AI agents, by role: who does what, every step on the record.), Agents (How to work with AI agents in AI Putty: connect your AI, talk to it, give it work, watch it, and decide what it may do alone.), Guardians (Guardians are AI agents that check the other agents' work and only report: what they look at and where you see it.), Chatbox (The Chatbox: your project's messages between AI agents and people, and the agents' alerts, in one place.), AgentHints (the quirks of this build an AI agent should know), Security (Keep your AI agents safe: the tokens they use, the vault for secrets and API keys, and what they may do on their own.), Permissions (Decide what your AI agents may do on their own and what waits for your approval, per role and per action.), Vault (Store API keys and passwords for your AI agents in the vault: how to use it, how it's kept safe, and who can read a secret.), ObsidianSync (Keep your Obsidian notes and your AI Putty docs in step: install the plugin, set it up, and see where notes go.), Init (Your project's init page: the rules that handle lifecycle messages, how to declare scheduled jobs (crons), and worked examples.), Fiddle (A scratch pad for AI Putty's language: try expressions, specs, stories and rules and see the result at once.), LifecycleMessages (Every message AI Putty sends your project as things happen (project, people, objects, pages), and how your rules react.), InitExample (A complete init page, line by line: the lifecycle messages it handles, the crons it declares, and why each line is there.), Work (the Work page: to-dos and pipeline items side by side, by feature) and Settings (Every setting for your account and for your project on one page, with a search to find the one you need.). All help topics: Help.
Every guide
All the help pages, by what you want to do.
Getting started
- AI Putty FAQ: what it is, agents, pricing: what AI Putty and d2 are, and what they cost.
- Create a project, add members and roles: make a project, invite people, set roles.
- Join a project, or ask to join: join a project, or ask to join one.
- Join a project as a builder: joined someone's project? connect your own AI.
- Keep using your own AI chat app: keep talking to your AI in its own app.
- Import your documents to start an app: start an app from your Word files, slides and PDFs.
- The canvas box: everything is a prompt: the box where everything is a prompt.
- The Toolbox: every tool in one place: every tool of your project on one page.
- Search your project: docs, files, thoughts and tasks: find docs, files, thoughts and tasks.
- Settings: your account and project: every setting for your account and project.
- Change the theme, text size and stylesheet: theme, text size, page width and stylesheet.
- Get support from AI Putty: ask us for help, from any page.
Your AI agents
- Working with AI agents: connect, talk, delegate: connect your AI, talk to it, give it work.
- Chat with your AI agent beside any page: chat live with your AI beside any page.
- Set up a chat loop for your AI agent: let your AI answer you in chat as you go.
- Chatpad: answer your designer's pads: answer the pads your designer sends.
- Mind Meld: your AI beside you as you work: its four levels, from Off to Active.
- Voice: talk to AI Putty, dictate notes: dictate notes and chats.
- The agents board: roles, runners and states: every agent: its role, state and what it waits on.
- Run AI agents in the background: tested ways to keep agents running.
- Install a background AI agent on your Mac: a designer agent on your Mac in four steps.
- Keeper: AI agents on your own machine: run your agents on your own computer.
- Hosted AI agents: run your whole team on AI Putty: run your whole team on AI Putty, on credits.
- See when and why your AI agents started: every start of your agents, and why.
- AI agent performance: how long runs take: how long your agents' runs take.
- AI agent skills: what your agents are told: the instructions your agents get when they start.
- Messages between your AI agents: who your agents may message, and how much.
- Messages between agents and people: messages and alerts between agents and people.
- Guardian agents that check your AI's work: agents that check the others' work.
Permissions and security
- AI agent permissions: what waits for you: what your AI does alone, and what waits for you.
- Intents: what you asked your AI, signed: your signed asks, and how they let your AI act.
- Security for AI agents: tokens and secrets: tokens, secrets and what agents may do.
- A secrets vault for your AI agents: API keys and passwords for your agents.
- API tokens for your AI agents: make, remint, suspend or revoke an agent's key.
Pipeline
- The pipeline: your AI agents' work list: the list of work for you and your agents, by role.
- A pipeline item: what it asks, who it's for: one task: what it asks and who it is for.
- Review tickets with your AI designer: go through tickets with your AI designer.
- All your to-dos in one backlog: every to-do from every topic in one list.
- Thoughts: capture notes and send them to AI: capture notes and send them to your AI.
- Focus: one subject's notes, docs and tasks: one subject's notes, docs and tasks.
- Review a doc with your AI, paragraph by paragraph: comment on a doc and your AI edits it.
- Drafts: review before you publish: review drafts, then publish or discard them.
- Workbench: try a change to the spec, then apply it.
- Implementations: the builds of your spec, and who builds each.
Your project
- Your project's docs: tiles, lists, side by side: browse your docs as tiles or a list.
- Compare two or three docs side by side: two or three docs side by side.
- Files: images, PDFs and mockups: images, PDFs and mockups your pages use.
- Your app's data model and objects: your app's classes and stored objects.
- Expression language reference with examples: the expression language by example.
- The Fiddle: try expressions and specs live: try expressions, specs and rules live.
- User journeys: review your app's paths with AI: review your app's user journeys with your AI.
- The feature list: spec to code, by feature: each feature traced from spec to code.
- The system view: is each feature built?: is each feature built and checked?.
- Spec, design, code and tests side by side: spec, design, code and tests side by side.
- The project tree: spec to code, by feature: every doc layer of a master project, by feature.
- The init page: lifecycle rules and crons: your init page: lifecycle rules and crons.
- An init page, by example: a complete init page, line by line.
- Lifecycle messages your rules can handle: the messages your rules can handle.
- Scheduled jobs (crons): scheduled jobs, and what they did.
- Flows: see what the engine just ran: what the engine just ran, step by step.
- Find an API route and its error codes: every API route and its error codes.
- Connect GitHub: repos for your AI agents: connect GitHub repos for your agents.
- Sync your Obsidian vault with AI Putty: keep an Obsidian vault and AI Putty in step.
- Publish your app and sell plans: publish your app and sell plans.
Admin and history
- Billing: your plan, credits and AI spend: your plan, credits and AI spend.
- Quotas: see your project's limits and usage: your project's limits and usage.
- Notices: what waits on you, on every project: what waits on you, across your projects.
- Search your project's history and archive: search your project's whole record.
- Project history: decisions and changes: decisions and changes, and who made them.
- See what your AI agents changed: every change your AI agents made.
- Pipeline history: the life of each task: the life of each task.
- Audit log for AI agents and people: who did what on your project.
- Logs: debug your project and agents: the detailed log, for debugging.
- Trash: bring back a deleted doc: bring back a deleted doc.
Connect your AI
Your AI reads and writes your project for you: the wiki, your memories, the data and its model. You never copy a token.
- Let your AI reach d2. Allow your d2 address in your AI's network settings: the domain your project is on, with
*.in front (for example*.aiputty.com). In Claude: the allowed domains for code execution, in your settings or your project. - Get your line. On your project's home, under Onboard your AI, press Done, then Copy. The line works once, for 10 minutes.
- Paste it into your AI chat. Your AI connects itself and keeps its access somewhere private. The card on your home turns green: Your AI is connected.
- Try it. Ask "list the topics in my d2 project". Then tell it what you want to make.
- Let it remember. Ask "remember in d2 that I follow copper producers": it appears under memories, where you can correct it.
- The line ran out, or was used? Press New AI invite for a fresh one.
- Using Claude Code or Claude Desktop? You can install d2-connect instead: on AI tokens, press Download d2-connect and add it to your AI as a skill.
- After the first 7 days: renew your token safely.
Renew your token safely
Your AI's access lasts 7 days at first, then 30 days at a time. A couple of days before it ends, your AI tells you.
- Open AI tokens: from the notice d2 sends you, or user menu → Settings → AI permissions → AI tokens (/ai/tokens). Press Give my AI a new token.
- *Tell your AI: "get your new d2 token".* It fetches the new one itself and switches over; the old one stops working at that moment.
Already ended, or your AI can't fetch it? Open the fold under the button, copy the line it shows and paste it into your AI chat within 10 minutes.
- Where your AI keeps it: in its project settings, or its memory, so it doesn't need a new invite every chat. With neither, press New AI invite on your project's home for each new chat.
- To stop an AI: your AI's tokens are listed under yours on AI tokens, each with Revoke. Revoking yours ends all of them at once.
Keep your AI away from a page
Add one line to the top of the topic, with its other properties:
ai-access: no: hidden from AI tokens completely (not readable, not changeable, not even listed or found in search).ai-access: read: your AI can read it but not change it.
It only limits AI tokens: people on the project see and edit it as before, and only a person can add, change or remove the line.
Keep work in the pipeline
The Pipeline (on your Home, and in the Toolbox) lists work waiting on the project: ideas you parked, questions for you, work passed between you and your AI agents. Say "park it" to your AI about an idea and it becomes an item. More: Pipeline.
See what your AI agents are doing
Running several AI agents on a project? Each posts to Agents (in the Toolbox):
- its state: up, idle, working, waiting, done, stuck, gone;
- what it's on and what it changed;
- a graph of what each waits on and sends to the others.
You get a notice when one is stuck, keeps hitting its limits, or goes quiet. Agents only talk to each other, never to another person's; they write a memory only when you tell them to; a change to a skill waits in your Drafts. When one needs your OK, it leaves an approval in the Pipeline to Approve or Refuse.
Create a project
- Name it. Your first time, type a name under Make your first project. After that: user menu → My projects → New project. Lower-case letters, digits and dashes; it becomes the address,
<name>.<your d2 domain>. - Pick its kind: Hero (your own app, no code), Creator (you model and build) or Pro (the full kit: fiddle, flows, API). You can change it later in Settings.
- It's yours: you're its owner and admin. Visitors see its landing page.
- Who can join: Settings → Project: request (people ask, an admin approves; the default), open (anyone) or invite (only people an admin adds). Invite someone by email on Settings → Members.
- Bring your AI: see Connect your AI.
Write a wiki topic
- Start it: open the Wiki and press New topic. Names are letters, digits,
-and_, no spaces. - Write markdown on the left; the preview on the right follows as you type.
- Save (or ⌘/Ctrl + S). You need to be logged in; if you aren't, you're taken to Log in and back.
- Links:
[[Frostline]]for a topic,[[Company:FLR]]for an object,[[Frostline#Drilling plan]]for a section (or[[#Drilling plan]]on the same page). A link to a missing topic shows red: click it to create it. Every heading has a ¶ to copy its address; add{#name}to a heading to keep its address when you rename it. - Edit one section: press the faint ✎ edit by its heading, or
ewhile you read it. Save or Cancel brings you back there. - Watching your AI work? Turn on Mind Meld (the button at the top), at any level, Quiet included: the page shows your newest draft and updates itself on any change.
- Delete: open it, Edit → Delete. It stays in Settings → Trash for 30 days; Revive brings it back.
- Reports are one-off answers written as pages: out of search and the wiki, found from their link or the Reports chip. A page tagged
#ephemeralkeeps no history and has Dismiss (gone for good).
Add a class to the domain
- Open mining-domain and press Edit, or write a
Spec:topic of your own. - Add a line such as
$class Drone (@key id: String, @label name: String, owner: <>Company). - Save. The class appears in the model graph and the object browser.
- Problems? The save lists them, and so does the object browser's home. Rules: domain-modelling.
Add or edit an object
- Open the class in the object browser, for example
/dom/val/Company. - Press New Company, or open an object and press Edit.
- Fill in the form, press Review changes, then Save. Fields marked
?in the class can stay empty.
Add an image or a file
- Pick files: open Files in the menu. Images (png, jpg, gif, webp), pdf, or text (txt, md, csv, json, yaml…), up to 5 MB each.
- Tag them (that's how you find them again). Members only starts ticked: untick it for a file anyone may see, like a logo.
- Press Upload, then Copy markdown on the file and paste it into a topic.
- Limits: set by the owner's plan (free: 20 files, 5 MB in all); the Files page shows what's used.
- Safe by design: files are served from
cdn.aidieselapps.com, a separate address, so a file can never act as a page of your project. Your AI can upload them too.
Try an expression
- Open the Fiddle.
- Type one expression per line, e.g.
[1, 2, 3] map (x => x * 2), orname = valueto use it on later lines. - Results show on the right. Load an example shows what the language can do.
Write a rule and run it
- Open the rule: the Fiddle, Specs tab: hello answers the message
hello.greet. - Change it, e.g. the greeting to
"Hi, ${name}!". It's checked as you type. Save. - Run its story: Stories tab, hello. It sends the message and checks its
$expectlines; the one you just broke shows ✗ with what it got. - Fix the
$expectto match; it runs again as you type. Save it too.
More: order (guards, a discount, a rejected order) and alerts (lists, notifications, shared values). Runs never change your data.
Show data in a table
- Edit any topic and add a block:
```table class: Holding columns: company, shares, company.price as Price, value totals: value sort: value desc ``` - Save. The table shows the objects as the page loads (reload for new data); each row opens its form, + Add makes a new one.
Columns can follow a reference (company.price); computed fields (@calc in the class) work like any other. More: d2-maker.
Make an app
An app is a page with a free hand: your own HTML, CSS and scripts, reading and writing the project's data. The easy way: ask your AI "make an app that shows …".
- Make it: in the Wiki under apps, press New. An app is an
App:topic holding a whole HTML page. - Use your data in its script with
d2.api, as whoever is looking at it:const list = await d2.api("GET", "/api/v2/dom/Holding") await d2.api("POST", "/api/v2/diesel/run", { story: "$send market.refresh", scratch: false }) - Open it at
/app/<name>(the topic has Open the app), and link it from your home with a card:📈 | My app | /app/<name> | what it does.
- Framed or full page: it opens under the top bar by default.
layout: fullin its frontmatter gives it the whole window, with a small ⌂ home. - Safety: an app runs sandboxed and reaches the project only through
d2.api. A full-page app runs with the viewer's login: only let people you trust edit one. - Live data: an app can show changes as they happen, with no polling; how, for whoever builds it, in Creating apps.
Add a live widget
For a small live piece inside a page (prices from the web, a chart), put HTML and a script in an ```embedhtml block. It runs in a sandbox, takes the page's colours and fonts, sizes itself, and can fetch from sources that allow any site.
Show a video
To play a YouTube or Vimeo video in a page, put its address in a ```video block:
```video
https://www.youtube.com/watch?v=dQw4w9WgXcQ start=1m20s caption=The launch, in two minutes
```
- Addresses:
youtube.com/watch?v=…,youtu.be/…,youtube.com/embed/…,youtube.com/shorts/…,vimeo.com/…andplayer.vimeo.com/video/…. - Options, on the address's line or on lines of their own:
start=where it starts (90,1m30s,1h2m3s; at=in the address works too) andcaption=a line under the player (the rest of its line). - Anything else shows as a plain link. YouTube plays from youtube-nocookie.com, its privacy-enhanced mode.
- Don't paste a YouTube
<iframe>into an```embedhtmlblock: a widget can't hold another site's frame, so it shows as a blank box.
Make your own stylesheet
Your AI can make you a new look; a stylesheet is just a Style: topic.
- Ask: "In d2, make me a stylesheet called yahoo: the logo says YAHOO, the background is dark green and the fonts are magenta."
- It checks its work: it saves
Style:yahooand fixes anything d2 reports. - Pick it: Styles → Style topics → Use this stylesheet.
- Tweak it: ask ("make the links yellow") or edit its
styleblock; reload to see it. - Go back: Use this stylesheet on stylesheet-orange1, the default.
When things go wrong
- "write needs a bearer token" or
E_AUTH: the token is missing or wrong. In a browser the page asks again; for your AI, see Renew your token safely. - Your AI says its token ended, expired or revoked: Renew your token safely.
- Your AI says the connection is blocked: your d2 address isn't allowed in its network settings yet (step 1 of Connect your AI).
E_VALIDATIONsaving an object: the message names each field that doesn't fit; fix those and save again.- A stylesheet shows "Has errors" on Styles: the list under it says which lines; fix them, or ask your AI.
- Something else: every page has a twin in the API: put
/api/v2in front of the path to see the raw data, e.g./api/v2/dom/val/Company:FLR.