Creating Taubyte Resources

Creating Taubyte Resources

When to use

• "Add a domain / website / library / function / database / storage / messaging / service"
• "Create an application for app-scoped resources"
• Building out a project after bootstrapping-taubyte-projects
• Reviewing or scripting non-interactive resource creation

Intent-first resource planning (agent behavior)

When a user asks to "create an app" (not just a resource), first infer the minimum Taubyte resource set required to make that app real, then create those resources with correct scope + wiring.

General heuristics:

• Web app UI → create a website (project-scoped if needed or mentioned) + a domain (project-scoped if mentioned) and attach the site to the domain and path(s).
• Persistent data → create a database (application-scoped if needed). create storage if needed ; choose only when implied by the intent.
• UI ↔ data/API glue → create at least one HTTP function that reads/writes the database and returns JSON for the website to consume. Attach the function to the same domain when a same-origin /api/... pattern is implied.

Rules while doing this:

• Prefer the fewest resources that satisfy the intent, but do not omit the glue (e.g. database without a function is usually not an "app").
• Keep scopes correct: database/storage/messaging/service are application-scoped if needed or mentioned; website/domain are project-scoped if needed or mentioned.
• Use match strings as stable wiring keys (database match, messaging channel, service protocol) and keep them consistent with Go calls and triggers (see enforcing-taubyte-constraints rule 16).

Preconditions

• tau --defaults --yes json current shows the correct Project (and the right Application, or none, depending on scope) — see selecting-taubyte-context.
• Project has been created/imported — see bootstrapping-taubyte-projects.

Scope rule (project vs application)

For app-scoped resources: tau --defaults --yes select application --name <app> first; for project-scoped, ensure no application is selected (tau --defaults --yes clear application).

Domains

Generated FQDN (Dream / quick demos)

tau --defaults --yes new domain <domain_name> \
  --generated-fqdn \
  --type auto \
  --description "<desc>"

Result: a random FQDN of the form <random>.<universe>.localtau.

Custom FQDN (remote, controlled hostname)

tau --defaults --yes new domain <domain_name> \
  --fqdn <fqdn> \
  --type auto \
  --description "<desc>"

Some remotes: *.gen.<cloud_fqdn> and the project CID suffix

Host policy can require that a generated-style hostname under *.gen.<cloud> embed the last eight characters of the project’s canonical CID from tau query project <name> --json → id. Compute: python3 -c "s='<cid>'; print(s[-8:])". Omitting this substring breaks config-compile with errors like does not contain last 8 of project id. When replacing a domain for this reason, reuse the same logical domain resource name (e.g. generated) if you can — so domains: on websites/functions stay valid without mass YAML edits.

Forbidden flag

Never pass --generated-fqdn-prefix (or --g-prefix) — it's not supported by policy. Use --generated-fqdn alone or use --fqdn with a controlled hostname.

Websites

Use the CLI to create websites and let the generated repo default to tb_website_<project>_<site> instead of tb_code_<project>_<site>.

tau --defaults --yes new website <site_name> \
  --domains <domain_name> \
  --paths / \
  --template empty \
  --generate-repository \
  --repository-name tb_website_<project>_<site_name> \
  --private \
  --no-embed-token \
  --branch main

tau --defaults --yes import website <site_name>
tau --defaults --yes list websites

Notes:

• --generate-repository creates a separate GitHub repo for the website; pair with a deterministic --repository-name (recommended: tb_website_<project>_<site>).
• After creation, run import website so the local clone appears under <project>/websites/<repo>/.
• Author build content under .taubyte/build.sh writing to /out — see building-taubyte-websites.

To attach an existing website repo instead of generating one, use --repository-name <fullname> or --repository-id <id> and drop --generate-repository.

Libraries

tau --defaults --yes new library <lib_name> \
  --path /libraries/<lib_name> \
  --template empty \
  --generate-repository \
  --repository-name tb_code_<project>_<lib_name> \
  --private \
  --no-embed-token \
  --branch main

tau --defaults --yes import library <lib_name>
tau --defaults --yes list libraries

--path is the path inside the library repo where sources live; it must match the actual layout in the cloned repo.

HTTP functions

tau --defaults --yes new function <fn_name> \
  --type http \
  --method GET \
  --paths /<path> \
  --domains <domain_name> \
  --language Go \
  --source . \
  --memory 64MB \
  --timeout 30s \
  --call <ExportedHandler> \
  --template empty

Or use a known-good ping_pong template:

tau --defaults --yes new function ping \
  --type http --method GET --paths /ping \
  --generate-domain \
  --language Go --source . \
  --memory 64MB --timeout 1s \
  --call ping \
  --template ping_pong --use-template

Function rules:

• One function per (path, method) — never comma-separated methods.
• --call must equal a //export <name> symbol in the source.
• For Go, edit the function root empty.go (next to go.mod) — never create a lib/ tree or hand-author main.go.

Applications

tau --defaults --yes new application <app_name> \
  --description "<desc>"
tau --defaults --yes select application --name <app_name>
tau --defaults --yes list applications

Databases (application-scoped)

tau --defaults --yes new database <db_name> \
  --match <matcher> \
  --min 1 --max 2 \
  --size 1GB

Constraint observed: --min 1 --max 1 fails with min(1) cannot be greater than max(1). Use --min 1 --max 2 (or higher max).

The --match value is the runtime key: Go code must call database.New("<matcher>") with the identical string (including any leading /).

Storage (application-scoped)

tau --defaults --yes new storage <storage_name> \
  --match <matcher> \
  --size 1GB \
  --bucket Object \
  --public

Messaging (application-scoped)

tau --defaults --yes new messaging <msg_name> \
  --match <channel_match> \
  --mqtt --ws

The <channel_match> is the channel string. Producers in Go call pubsub/node's Channel("<channel_match>"), and PubSub-triggered functions set trigger.channel: <channel_match>.

Services (application-scoped)

tau --defaults --yes new service <svc_name> \
  --protocol /api

On Git Bash / MSYS, prefix path-like flags with MSYS_NO_PATHCONV=1 to avoid path mangling.

Workflow checklist for a typical project

Resource creation progress:
- [ ] Verify selection (tau --json current)
- [ ] Create domain (project scope)
- [ ] Create website + import (project scope)
- [ ] Create library + import (project scope)
- [ ] Create application
- [ ] Select application
- [ ] Create database / storage / messaging / service
- [ ] Create functions (HTTP at project scope, others at app scope as needed)
- [ ] tau clear application
- [ ] tau push project --config-only --message "..."
- [ ] Wait for config build success before pushing website/library code

Gotchas

• Dream vs CLI vs remote WASM paths: tau new function ... --source . with an application selected may scaffold under code/applications/<app>/functions/<fn>/ in your clone, while Dream or remote builders often expect code/<app>/functions/<fn>/ (no applications/ segment). A remote job may fail with couldn't find .taubyte under .../<app>/functions/<fn> while your tree still has .../applications/<app>/functions/<fn>. Treat the path in the first failing build log as ground truth and move the function directory (and fix any relative references) so .taubyte/ sits where the builder looks — do not guess a different layout.
• Application bleed: forgetting tau clear application causes later tau new domain|website|library to land in the app instead of project scope.
• Matcher = runtime string: match in YAML must equal the literal Go calls (database.New("..."), pubsubnode.Channel("..."), trigger.channel). Mismatched leading / is a frequent cause of "open failed" / silent producers.
• Repo strategy must be explicit for websites/libraries — either --generate-repository with a deterministic --repository-name, or --repository-name/--repository-id for an existing repo.
• Don't hand-edit domain YAML. Always use tau new domain / tau delete domain / tau query domain.
• Min/max on database: --min must be strictly less than --max.

Related skills

• bootstrapping-taubyte-projects
• selecting-taubyte-context
• pushing-taubyte-projects
• building-taubyte-websites
• verifying-taubyte-functions