> For the complete documentation index, see [llms.txt](https://docs.urbit.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.urbit.org/urbit-os/base/threads/api.md). # Spider API Reference Spider API reference for starting, stopping, and interacting with threads. Pokes, subscriptions, and thread lifecycle management. This document describes Spider's API. Note it's usually better to run threads via the Khan vane than Spider directly, unless you need to interact with the thread while it's running. You can refer to the [Khan documentation](/urbit-os/kernel/khan.md) for details. ## Run thread file Poke Spider with mark `%spider-start` and a vase containing `$start-args:spider`: ```hoon +$ start-args $: parent=(unit tid) use=(unit tid) =beak file=term =vase == ``` Where: * `.parent` - optional `$tid` of parent thread if the thread is a child. If specified, the child thread will be killed with the parent thread ends. * `.use` - `$tid` (thread ID) to give the new thread. Can be generated with something like `(scot %ta (cat 3 'my-agent_' (scot %uv (sham eny))))`. However you do it, make sure it's unique. * `.beak` - A `$beak` is a triple of `[p=ship q=desk r=case]`. `.p` is always our ship, `.q` is the desk which contains the thread we want to run. `.r` is a `$case`, which specifies a desk revision and is a tagged union of: ```hoon +$ case $% [%da p=@da] :: date [%tas p=@tas] :: label [%ud p=@ud] :: number == ``` You'll almost always just want the current revision, so you can specify the `$case` as `da+now.bowl`. If the thread is on the same desk as the agent you can also just use `byk.bowl(r da+now.bowl)` for the `.beak`. * `file` - name of the thread file in `/ted`. For example, if the thread you want to start is `/ted/foo/hoon` you'd specify `%foo`. * `.vase` - `$vase` to be given to the thread when it's started. Can be whatever or just `!>(~)` if it doesn't need any args. #### Example ```hoon [%pass /some-path %agent [our.bowl %spider] %poke %spider-start !>([~ `tid byk.bowl(r da+now.bowl) %foo !>(~)])] ``` ## Run inline thread Poke Spider with mark `%spider-inline` and a vase containing `$inline-args:spider`: ```hoon +$ inline-args $: parent=(unit tid) use=(unit tid) =beak =shed:khan == ``` Where: * `.parent` - optional `$tid` of parent thread if the thread is a child. If specified, the child thread will be killed with the parent thread ends. * `.use` - `$tid` (thread ID) to give the new thread. Can be generated with something like `(scot %ta (cat 3 'my-agent_' (scot %uv (sham eny))))`. However you do it, make sure it's unique. * `.beak` - A `$beak` is a triple of `[p=ship q=desk r=case]`. `.p` is always our ship, `.q` is the desk which contains the thread we want to run. `.r` is a `$case`, which specifies a desk revision and is a tagged union of: ```hoon +$ case $% [%da p=@da] :: date [%tas p=@tas] :: label [%ud p=@ud] :: number == ``` You'll almost always just want the current revision, so you can specify the `$case` as `da+now.bowl`. If the thread is on the same desk as the agent you can also just use `byk.bowl(r da+now.bowl)` for the `$beak`. * `.shed` - the inline thread itself. #### Example ```hoon =/ =shed:khan =/ m (strand:rand ,vase) ^- form:m (pure:m !>(txt)) =/ tid `@ta`(cat 3 'thread_' (scot %uv (sham eny.bowl))) :_ this [%pass /some-path %agent [our.bowl %spider] %poke %spider-inline !>([~ `tid byk.bowl(r da+now.bowl) shed])]~ ``` ## Stop thread Poke Spider with mark `%spider-stop` and a vase containing `[tid ?]`, where: * `.tid` - the `$tid` of the thread you want to stop * `?` - whether thread should end nicely. If `%.y` it'll end with mark `%thread-done` and the bunt value of a vase. If `%.n` it'll end with mark `%thread-fail` and a `[term tang]` where `$term` is `%cancelled` and `$tang` is `~`. #### Example ```hoon [%pass /some-path %agent [our.bowl %spider] %poke %spider-stop !>([tid %.y)] ``` ## Subscribe for result Spider will send the result on `/thread-result/[tid]` so you can subscribe there for the result. You should subscribe before starting the thread. The result will have a mark of either `%thread-fail` or `%thread-done`. * `%thread-fail` - has a vase containing a `[term tang]` where `$term` is an error message and `$tang` is a traceback. * `%thread-done` - has a vase of the result of the thread. #### Example ```hoon [%pass /some-path %agent [our.bowl %spider] %watch /thread-result/[tid]] ``` ## Subscribe to thread You can subscribe to a thread on `/thread/[tid]/path`. Note this is for facts sent off by the thread while it's running, not the final result. The path depends on the particular thread. #### Example ```hoon [%pass /some-path %agent [our.bowl %spider] %watch /thread/[tid]/thread-path] ``` ## Poke thread To poke a thread you poke Spider with a mark of `%spider-input` and a vase of `[tid cage]`. * `$tid` is the tid of the thread you want to poke * `$cage` is whatever mark and vase you want to poke it with #### Example ```hoon [%pass /some-path %agent [our.bowl %spider] %poke %spider-input !>([tid %foo !>('foooo')])] ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.urbit.org/urbit-os/base/threads/api.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.