Quickstart

Install the AutoKitteh CLI Tool

Run this command on macOS:

brew install autokitteh/tap/autokitteh

tip

For other operating systems and other methods, see the Installation page.

To enable shell completion, follow these instructions.

Start a Self-Hosted Server

Run this command to start a self-hosted AutoKitteh server in "dev" mode:

ak up --mode dev

tip

For a discussion of the different server execution modes, see the Start Server page.

Create and Deploy a Project With the CLI Tool

An AutoKitteh project is a collection of settings and code that implements workflows.

Let's use an existing project from the Kittehub repository to create a basic workflow that starts when AutoKitteh receives an HTTP request, and prints a simple message to AutoKitteh's session log.

Run this command to clone the Kittehub repository, which contains various project directories:
```
git clone https://github.com/autokitteh/kittehub.git
```
Alternatively, download and extract the repository's zip archive file

Run this command:

ak deploy --manifest kittehub/quickstart/autokitteh.yaml

Under the hood

The ak deploy command does the following:

Create a new Autokitteh project
Apply the project settings from the YAML manifest file
Build (i.e. lint, compile, and package a snapshot of) the source code
Deploy this build
Activate this deployment

Expected output

[plan] project "quickstart": not found, will create
[plan] trigger "quickstart/default:/http_request": not found, will create

[exec] create_project "quickstart": created "prj_aaaaaaaaaaaaaaaaaaaaaaaaaa"
[exec] create_trigger "quickstart/default:/http_request": created "trg_bbbbbbbbbbbbbbbbbbbbbbbbbb"

[!!!!] trigger "http_request" created, webhook path is "/webhooks/cccccccccccccccccccccccccc"

[exec] create_build: created "bld_dddddddddddddddddddddddddd"
[exec] create_deployment: created "dep_eeeeeeeeeeeeeeeeeeeeeeeeee"
[exec] activate_deployment: activated

That's it! The project is now waiting for trigger events in order to start runtime sessions that run workflows.

Trigger the Deployment

Look for the following line in the output of the ak deploy command, and copy the URL path:
```
[!!!!] Trigger "http_request" created, webhook path is "/webhooks/..."
```
tip
If you don't see the output of ak deploy anymore, you can run this command instead, and use the webhook slug from the output:
ak trigger get http_request --project quickstart -J
Run this command (use the URL path from step 1 instead of /webhooks/...):
```
curl -i "http://localhost:9980/webhooks/.../"
```
Explanation
The curl flag -i shows you the server's response.
localhost:9980 is the address of the local AutoKitteh server that you started (with the default port number).
/webhooks/... is the URL path of the project's trigger, which is defined in the YAML manifest file, and was assigned when you deployed the project for the first time.

Run this command to check that a runtime session has indeed started and ended:

ak session list -J

Expected output

{
    "session_id": "ses_wwwwwwwwwwwwwwwwwwwwwwwwww",
    "event_id": "evt_xxxxxxxxxxxxxxxxxxxxxxxxxx",
    "deployment_id": "dep_ffffffffffffffffffffffffff",
    "build_id": "bld_eeeeeeeeeeeeeeeeeeeeeeeeee",
    "env_id": "env_bbbbbbbbbbbbbbbbbbbbbbbbbb",
    "entrypoint": {
        "path": "program.py",
        "name": "on_http_get"
    },
    "created_at": "2024-03-22T00:12:34.123456Z",
    "updated_at": "2024-03-22T00:12:35.123456Z",
    "state": "SESSION_STATE_TYPE_COMPLETED"
}

Run this command to display all the print messages in the latest session's log:

ak session log --prints-only

[2024-03-22T00:12:34.123456 +0000 UTC] Received GET request
[2024-03-22T00:12:34.123456 +0000 UTC] Finished processing GET request

Resilience Demo

Run this command to trigger the deployment again, but this time with an additional query parameter (number of iterations = 50):
```
curl -i "http://localhost:9980/webhooks/...?iterations=50"
```
info
This runs the workflow as a stateful and long-running loop, instead of printing just a single message:
for i in range(iterations): print(f"Loop iteration: {i + 1} of {iterations}") time.sleep(FIVE_SECONDS)
Run this command:
```
ak session list -J
```
Notice
The current state of the new sessions is RUNNING rather than COMPLETED.

Run this command:

ak session log --prints-only

This command outputs several new print messages from the latest session's log, while it's still running:

[2024-03-22T00:12:34.123456 +0000 UTC] Received GET request
[2024-03-22T00:12:34.123456 +0000 UTC] Loop iteration: 1 of 50
[2024-03-22T00:12:39.123456 +0000 UTC] Loop iteration: 2 of 50
[2024-03-22T00:12:44.123456 +0000 UTC] Loop iteration: 3 of 50
...

Terminate the AutoKitteh server in any way you want, for example:
```
pkill -f -Il "ak up"
```
info
A naive server would lose its internal state when this happens, and lose the running workflow, or (even worse) abandon it to continue running as a zombie process without being able to regain ownership.
Either way, when you restart it, you would have to manually trigger the project deployment again, and the new workflow wouldn't remember its previous data or be able to resume without repeating steps that it already completed.
AutoKitteh is smarter than that!
Run this command to start the AutoKitteh server again:
```
ak up --mode dev
```
Run this command again, to see what happens after AutoKitteh restarts:
```
ak session list -J
```
Conclusion
AutoKitteh retains its configuration, history, and internal state across restarts!
Run this command again too, after a few seconds:
```
ak session log -p
```
Conclusion
AutoKitteh has automatically resumed the original session, without losing runtime state or workflow data!
Lastly, after about 4 minutes, run the last two commands again to see that the session has ended successfully

Appendix: HTTP Tunneling

Integrating third-party services and APIs with AutoKitteh usually requires AutoKitteh to expose publicly-accessible HTTPS endpoints, in order to support OAuth 2.0 and to receive asynchronous events.

There are many options to do this; a popular "freemium" solution is ngrok:

Install ngrok, according to step 1 here: https://ngrok.com/docs/getting-started/
Connect your ngrok agent to your ngrok account, according to step 2 in the same quickstart guide
Create a static domain on your ngrok dashboard: https://dashboard.ngrok.com/cloud-edge/domains
Run this command to start ngrok:
```
ngrok http 9980 --domain example.ngrok.dev
```
note
- 9980 is AutoKitteh's local HTTP port
- example.ngrok.dev is the domain you've registered in step 3
Set the environment variable WEBHOOK_ADDRESS, based on the step 3 above (just the address, without the https:// prefix, and without a path suffix, e.g. example.ngrok.dev)

Lastly, after adding/changing/removing server configurations and environment variables, restart the ak server, in order for them to take effect.

Install the AutoKitteh CLI Tool​

Start a Self-Hosted Server​

Create and Deploy a Project With the CLI Tool​

Trigger the Deployment​

Resilience Demo​

Appendix: HTTP Tunneling​