quikform

Your agent writes the form. quikform serves it.

A small open-source forms server. Your AI agent writes one JSON file, quikform checks it and serves a mobile-friendly form on your own domain. Every answer lands in a SQLite file your agent can read back.

  • One executable
  • Under 100 MB of RAM
  • Works without JavaScript
  • MIT licence
$ quikform form put \
    --project northwind onboarding.json
ok onboarding v1
A two-step onboarding form on a phone: name, email and a single-choice question, with a green Next button and a progress bar.
The form that onboarding.json describes, as quikform renders it on a phone. Northwind Climbing is a sample brand.

How it works

You describe the form in a sentence. Your agent does the rest with four commands.

  1. Your agent writes a JSON file

    Fields, steps, conditions, the thank-you message and the privacy note. No HTML, no scripts.

  2. quikform check reads it

    Every mistake comes back with its exact path in the file, so the agent fixes it before anyone sees the form.

  3. form put publishes it

    The form is live on your domain within ten seconds. Its version goes up each time the content changes.

  4. Answers come back

    Each answer is validated again on the server, saved to SQLite and, if you like, sent to a Telegram group. quikform responses gives them to your agent as JSON, and you can read them yourself in the admin.

Show one stage of the example
{
  "id": "onboarding",
  "lang": "en",
  "title": "Welcome to Northwind",
  "privacy":
    "Your answers are only used to plan your sessions.",
  "access": "public",
  "notify": { "telegram": true },
  "steps": [
    { "title": "About you", "fields": [
      { "id": "name", "type": "short_text",
        "label": "Your name", "required": true },
      { "id": "email", "type": "email",
        "label": "Email", "required": true },
      { "id": "level", "type": "single_choice",
        "label": "Have you climbed before?",
        "options": [ … ] }
    ] },
    { "title": "Your goals", "fields": [
      { "id": "injury", "type": "yes_no",
        "label": "Any injury we should know about?" },
      { "id": "injury_details", "type": "long_text",
        "label": "Tell us more",
        "showIf": { "field": "injury", "equals": true } }
    ] }
  ]
}
Step 1 of 2: name, email and climbing level filled in. Step 2 of 2: yes to the injury question, which reveals the Tell us more field.
$ quikform responses --project northwind --json
[
  {
    "id": 1,
    "created_at": "2026-10-23T09:19:34.566Z",
    "form": "onboarding",
    "version": 1,
    "values": {
      "name": "Maya Okafor",
      "email": "maya@example.com",
      "level": "some",
      "injury": true,
      "injury_details": "Old shoulder strain, mostly fine now."
    }
  }
]

What people build with it

Anything you would otherwise collect by email or WhatsApp and copy out by hand.

  • Client onboarding

    New members or clients answer once, on their phone, before the first meeting. Your agent reads the answers and prepares the session.

    short_text · email · single_choice · yes_no
  • A contact form for a static site

    Link your site's “Contact” button to forms.yoursite.com/contact. Messages reach your Telegram and stay in your database.

    email · long_text
  • A questionnaire for one client

    Prices, services, opening hours: everything an agent needs to know about a business, asked in steps instead of a long email thread. Each person gets their own private link, and the admin shows who has answered.

    number · multiple_choice · link create
  • Class or event sign-up

    A public link to share in a group chat. A hidden trap field and a submission limit keep bots out.

    short_text · email · single_choice
  • Feedback after a job

    A short form sent when the work is done. Follow-up questions appear only when an answer calls for them.

    yes_no · long_text · showIf
  • Requests your agent will handle

    Quote requests, bookings, intake forms: the answers arrive as structured JSON, ready for the agent that acts on them.

    responses --json

Why so small

  • Why should a contact form need an account on someone else's service?
  • Why should your agent click through a visual builder when it can write a file?
  • Why should a forms server need gigabytes of memory and several databases?
  • Why should your answers live anywhere but next to your project?

quikform keeps one JSON file per form and one SQLite file per project, on your server, behind the web server you already run. The field components are written once and tested, so every form your agent writes gets the same validation and the same comfort on a phone.

What's inside

Everything a form needs to be filled in on a phone and trusted on the server.

Seven field types
Short text, long text, email, number, single choice, multiple choice and yes/no. Each one can be required, have limits and help text, or appear only when another answer calls for it.
Checked twice
quikform check validates the definition before it goes live, and the server validates every submission again. A required field hidden by a condition never blocks the form.
Made for phones
Short forms fit on one page; long ones split into steps with a progress bar. Labels stay visible, the keyboard matches the field, the button sits under the thumb. Answers in progress are kept in the browser until the form is sent.
Works without JavaScript
The page is rendered on the server. The small script only adds steps, live validation and conditional fields.
Your brand, not ours
Logo and accent colour per project, and no “powered by” badge. No trackers and no cookie banner.
Alerts and privacy
A Telegram message for each answer. A privacy note on every form, and answers deleted after 12 months by default.
Four languages
Interface text in English, French, German and Thai, set per form.
Public or private
A public form answers anyone with its address. A private form answers only the links you create, one per person and revocable, and each answer records which link it came from.
A read-only admin
Behind a password, on a phone or a computer: your projects, their forms, who has answered, the links to share with a Copy button, and every answer question by question. It changes nothing; forms and links stay with your agent.
One domain for every project
Set a base domain once and each project answers on its own subdomain, such as gym.forms.example.com, with its HTTPS certificate fetched on the first visit. A project can also keep a domain of its own.
A skill for your agent
skills/quikform/SKILL.md tells your agent when to use quikform and walks it through writing, checking, publishing, private links and reading answers. Link it into Claude Code, or point any other agent at it.
# one project per domain
$ quikform project init northwind \
    --domain forms.northwind.example \
    --accent "#2b6a4f"

# the agent's whole toolkit
$ quikform check onboarding.json
$ quikform form put --project northwind \
    onboarding.json
$ quikform responses --project northwind --json

# a private form: one link per person
$ quikform link create --project northwind \
    --form onboarding --label "Maya"

# the server, behind Caddy or any reverse proxy
$ quikform serve --port 8787

Each command works on one project only. Exit codes: 0 success, 1 failure, 2 usage error.

Install

The quickest way is the ready-made Docker image, ghcr.io/jonathanvouilloz/quikform, for Linux amd64 and arm64: no clone and no build.

Without Docker, build one executable from source with Bun 1.4 or later and copy dist/quikform onto your server.

quikform listens on 127.0.0.1 only: put Caddy or another reverse proxy in front for HTTPS. The README covers the systemd unit, the Caddy block and turning on the admin.

# with Docker
$ mkdir quikform && cd quikform
$ curl -fsSLO \
    https://raw.githubusercontent.com/jonathanvouilloz/quikform/main/compose.yaml
$ echo "QUIKFORM_SECRET=$(openssl rand -hex 32)" > .env
$ docker compose up -d

# or from source, with Bun
$ git clone https://github.com/jonathanvouilloz/quikform
$ cd quikform
$ bun install
$ bun run build        # writes dist/quikform

$ export QUIKFORM_HOME=~/.local/share/quikform
$ export QUIKFORM_SECRET=$(openssl rand -hex 32)
$ ./dist/quikform serve

Open source, MIT licence

The code, the form format and the issues are on GitHub. Fork it, host it, send a pull request.

View on GitHub