tau Documentation

File: README.md Copy Chapter

Development Environment

Build Your Application

Deploy and Run

Quick Start Copy Chapter

Run Locally Copy Section

The quickest way to try Taubyte is to spin up a local environment with dream → https://tau.how/getting-started/local-cloud

Deploy Copy Section

Deploy Taubyte to your own Servers and/or VMs:

• Manual deployment → https://tau.how/platform/deployment
• Automated deployment with Spore Drive → https://tau.how/platform/spore-drive

Prefer Video? Copy Section

Check out the Hitchhiker's Guide to Taubyte for guided walkthroughs and demos:

Staying ahead Copy Chapter

Star us on GitHub and be instantly notified of new releases.

Contributing Copy Chapter

Tau thrives with your help. Fix bugs, add features, improve docs, or guide the community.

How to contribute

• Fork → branch from main → make changes → test → submit a PR
• Keep commits focused and describe what & why clearly
• New here? Look for good first issue

License Copy Chapter

BSD-3-Clause license. See LICENSE for details.

File: cdk/README.md Copy Chapter

Cloud Development Kit

Ops & Platform Engineering Copy Chapter

Deploying and operating a Taubyte Cloud, you should use:

• spore-drive:

• TypeScript: https://www.npmjs.com/package/@taubyte/spore-drive

• Python: https://pypi.org/project/spore-drive/

• taucorder

Development Copy Chapter

TODO

File: clients/http/patrick/README.md Copy Chapter

go-patrick-http

REST client for Patrick Node

Testing

Run Copy Chapter

go test ./...

Usage

// jid is a job id

c := New(ctx, URL(url string), Auth(token string), Provider(provider string))
jids, _ := c.Jobs(projectId string)

for _, jid := range jobs {
    _job, _ := c.Job(jid)
    _job.Logs // cid of the job's log file
    _job.Status // The status of the job  ( commonPatrick.JobStatus )
    _job.Meta.Repository.Id // The repository the job was ran on

    _job.TimeStamp // NOT IMPLEMENTED, TODO made in patrick/service/http_job.go

    readCloser, _ := c.LogFile(_job.Logs)

    // Print logs of the job to stdOut
    os.Copy(os.Stdout, readCloser)
}

File: pkg/taucorder/clients/js/README.md Copy Chapter

@taubyte/taucorder

Installation Copy Chapter

npm Copy Section

npm install @taubyte/taucorder

yarn Copy Section

yarn add @taubyte/taucorder

File: pkg/spore-drive/clients/js/README.md Copy Chapter

@taubyte/spore-drive

Gone are the days of relying on third parties to build and maintain cloud infrastructure for your software. spore-drive empowers you to deploy, scale, and manage your Tau cloud infrastructure with code!

Installation Copy Chapter

npm Copy Section

npm install @taubyte/spore-drive

yarn Copy Section

yarn add @taubyte/spore-drive

Example Usage Copy Chapter

Load Configuration Copy Section

Create a new configuration in memory:

import { Config } from "@taubyte/spore-drive";

const config = new Config();
await config.init();

Alternatively, load a configuration from a source, such as the local file system:

const config = new Config(`/absolute/path/to/config`);
await config.init();

Define Cloud Infrastructure Copy Section

You can define your cloud infrastructure as follows:

await config.cloud.set({
  domain: {
    root: "test.com",
    generated: "gtest.com",
  },
});
await config.cloud.domain.validation.generate();
await config.cloud.p2p.swarm.generate();

Or for more granular control:

await config.cloud.domain.root.set("test.com");
await config.cloud.domain.generated.set("gtest.com");
await config.cloud.domain.validation.generate();
await config.cloud.p2p.swarm.generate();

Set Auth Configurations Copy Section

await config.auth.set({
  main: {
    username: "tau1",
    password: "testtest",
  },
  withkey: {
    username: "tau2",
    key: "/keys/test.pem",
  },
});

Or

const mainAuth = config.auth.signer["main"];
await mainAuth.username.set("tau1");
await mainAuth.password.set("testtest");

const withKeyAuth = config.auth.signer["withkey"];
await withKeyAuth.username.set("tau2");
await withKeyAuth.key.path.set("/keys/test.pem");

Set Shapes Configurations Copy Section

await config.shapes.set({
  shape1: {
    services: ["auth", "seer"],
    ports: {
      main: 4242,
      lite: 4262,
    },
  },
  shape2: {
    services: ["gateway", "patrick", "monkey"],
    ports: {
      main: 6242,
      lite: 6262,
    },
    plugins: ["[email protected]"],
  },
});

Or

const shape1 = config.shape["shape1"];
await shape1.services.set(["auth", "seer"]);
await shape1.ports.port["main"].set(4242);
await shape1.ports.port["lite"].set(4262);

Set Hosts Copy Section

await config.hosts.set({
  host1: {
    addr: ["1.2.3.4/24", "4.3.2.1/24"],
    ssh: {
      addr: "1.2.3.4",
      port: 4242,
      auth: ["main"],
    },
    location: {
      lat: 1.25,
      long: 25.1,
    },
  },
  host2: {
    addr: ["8.2.3.4/24", "4.3.2.8/24"],
    ssh: {
      addr: "8.2.3.4",
      port: 4242,
      auth: ["withkey"],
    },
    location: {
      lat: 1.25,
      long: 25.1,
    },
  },
});

// Generate host instances key/id
await config.host["host1"].shape["shape1"].generate();
await config.host["host1"].shape["shape2"].generate();
await config.host["host2"].shape["shape1"].generate();
await config.host["host2"].shape["shape2"].generate();

Or

const host1 = config.host["host1"];
await host1.addresses.add(["1.2.3.4/24", "4.3.2.1/24"]);
await host1.ssh.address.set("1.2.3.4:4242");
await host1.ssh.auth.add(["main"]);
await host1.location.set("1.25, 25.1");
await host1.shape["shape1"].generate();
await host1.shape["shape2"].generate();

Set P2P Bootstrap Copy Section

await config.cloud.p2p.set({
  bootstrap: {
    shape1: ["host2", "host1"],
    shape2: ["host2", "host1"],
  },
});

Or

await config.cloud.p2p.bootstrap.shape["shape1"].nodes.add([
  "host2",
  "host1",
]);

Instantiate a Drive Copy Section

import { Drive, TauLatest } from "@taubyte/spore-drive";

const drive = new Drive(config, TauLatest);
await drive.init();

Plot a Course Copy Section

const course = await drive.plot(new CourseConfig(["shape1"]));

shape1 is used to select hosts to be deployed to.

Deploy Copy Section

await course.displace();

console.log("Displacing...");
for await (const progress of await course.progress()) {
    console.log(progress);
}
console.log("Done");

Progress Bars Copy Section

You can visualize the deployment progress using progress bars:

import { ProgressBar } from "@opentf/cli-pbar";

// Extracts the host from the given path
function extractHost(path: string): string {
  const match = path.match(/\/([^\/]+):\d+/);
  return match ? match[1] : "unknown-host";
}

// Extracts the task from the given path
function extractTask(path: string): string {
  const parts = path.split("/");
  return parts[parts.length - 1] || "unknown-task";
}

async function displayProgress(course: Course) {
  const multiPBar = new ProgressBar({ size: "SMALL" });
  multiPBar.start();
  const taskBars: Record<string, any> = {};
  const errors: { host: string; task: string; error: string }[] = [];

  for await (const displacement of await course.progress()) {
    const host = extractHost(displacement.path);
    const task = extractTask(displacement.path);

    if (!taskBars[host]) {
      taskBars[host] = multiPBar.add({
        prefix: host,
        suffix: "...",
        total: 100,
      });
    }

    taskBars[host].update({ value: displacement.progress, suffix: task });

    if (displacement.error) {
      errors.push({ host, task, error: displacement.error });
    }
  }

  for (const host in taskBars) {
    const errorForHost = errors.find((err) => err.host === host);

    if (errorForHost) {
      taskBars[host].update({ value: 100, color: "r", suffix: "failed" });
    } else {
      taskBars[host].update({ value: 100, suffix: "successful" });
    }
  }

  multiPBar.stop();

  if (errors.length > 0) {
    console.log("\nErrors encountered:");
    errors.forEach((err) => {
      console.log(`Host: ${err.host}, Task: ${err.task}, Error: ${err.error}`);
    });
  }
}

File: pkg/http-auto/README.md Copy Chapter

HTTP Auto Package

The http-auto package is a part of the Taubyte project, designed to facilitate automatic HTTP service management with features such as domain validation, TLS support, and caching.

Features Copy Chapter

• Automatic Domain Validation: Validates service or alias domains using TLS client hello information.
• TLS Support: Integrates with ACME for certificate management.
• Caching: Implements positive and negative caching for domain validation results.

Using a Custom ACME Server (StepCA) Copy Chapter

Install StepCA Copy Section

If you already have StepCA installed, skip this step. Otherwise, follow this simple guide to run a local instance for testing.

1. Pull the StepCA Docker image:

   bash Copy

   docker pull smallstep/step-ca

2. Run the StepCA container:

   bash Copy

   docker run -d --name step-ca \
     -v step:/home/step \
     -p 9000:9000 \
     -e DOCKER_STEPCA_INIT_NAME=StepCA \
     -e DOCKER_STEPCA_INIT_DNS_NAMES=localhost \
     smallstep/step-ca

3. Ensure it's running:

   bash Copy

   curl http://localhost:9000/health

4. Connect to the container:

   bash Copy

   docker exec -it step-ca sh

5. Add an ACME provider:

   bash Copy

   step ca provisioner add acme --type ACME

6. Restart the container:

   bash Copy

   docker restart step-ca

Configure Tau Copy Section

Edit the configuration file for your setup and add the following:

domains:
    acme:
        url: https://localhost:9000/acme/acme/directory
        ca:
            skip: true

If you want to add a RootCA, use:

domains:
    acme:
        url: https://localhost:9000/acme/acme/directory
        ca:
            root-ca: "/path/to/root/ca/file"
            caa-record: "myca.org"

File: tools/taucorder/npm/README.md Copy Chapter

taucorder is a cloud disgnostics tool. For documentation, visit https://tau.how.

File: tools/tau/npm/README.md Copy Chapter

tau is a command line tool for interacting with a Taubyte-based Cloud Network. Similar to the web console, it allows you to create and manage projects, applications, resources, and more.

Installation Copy Chapter

npm i @taubyte/cli

Documentation

For documentation head to tau.how

File: tools/tau/README.md Copy Chapter

Tau CLI

Local Coding Equals Global Production

tau is a command-line interface (CLI) tool for interacting with Taubyte-based Clouds. It enables users to create, manage projects, applications, resources, and more directly from the terminal.

Installation Copy Chapter

NPM Copy Section

npm i @taubyte/cli

Self extracting Copy Section

curl https://get.tau.link/cli | sh

Fetch and Install with Go Copy Section

go install github.com/taubyte/tau/tools/tau@latest

You can rename tau-cli to tau or create an alias.

Clone and Build Copy Section

git clone https://github.com/taubyte/tau/tools/tau
cd tau
go build -o ~/go/bin/tau

Offline version (Optional) Copy Section

Fails faster if exploring an unregistered project

go build -o ~/go/bin/otau -tags=localAuthClient

Login Copy Chapter

tau login
- opens selection with default already selected
- simply logs in if only default available
- will open new if no profiles found
tau login --new for new

• --set-default for making this new auth the default
  tau login for using a specific profile

Environment Variables: Copy Chapter

• TAUBYTE_PROJECT Selected project
• TAUBYTE_PROFILE Selected profile
• TAUBYTE_APPLICATION Selected application
• TAUBYTE_CONFIG (default: ~/tau.yaml) Config location
• TAUBYTE_SESSION (default: /tmp/tau-<shell-pid>) Session location
• DREAM_BINARY (default: $GOPATH/dream) Dream binary location

Testing Copy Chapter

All tests Copy Section

go test -v ./...

Flow tests live in each resource package (e.g. cli/commands/resources/application/flow_test.go, cli/commands/login/flow_test.go) and use cli/testhelper and testutil (auth mock via gock). ## Running Individual Prompts

go run ./prompts/internal

Measuring Coverage Copy Chapter

To avoid "error generating coverage report: write |1: broken pipe" (common when running many packages with -cover), use:

make test-cover

This runs tests with coverage for all packages and writes cover.out.

Display coverage Copy Section

go tool cover -html=cover.out
go tool cover -func=cover.out

Documentation

For documentation head to tau.how