content/getting-started/cli.md · urbit.org

git.iko.soy/urbit.org

on 20b8421 help sign in

urbit.org/content/getting-started/cli.md

290 lines 9.8 kB history raw

1+++

2title = "Command-line install"

3weight = 3

4description = "Installation instructions for technical users"

5tag = "selfhost"

6+++

8This guide covers running the Urbit runtime (Vere) using the command line. This

9can be run on your local machine or a server in the cloud, we just cover the

10local case here. The runtime is what interprets the Urbit kernel code (Arvo)

11into commands your specific machine (macOS or Linux) understands.

13Note there is a much more comprehensive [cloud hosting

14guide](/getting-started/cloud-hosting) which walks through setting up Urbit on a

15[Digital Ocean](https://www.digitalocean.com/) VPS.

17### 1. System Requirements {% #about-swap-space %}

19- **Processor**: 1 core

20- **Memory**: 2GB

21- **Storage**: At least a few GB, 40-50GB preferable

22- **Network**: Any

24**A note on memory**: By default, the Urbit runtime needs 2GB of free memory,

25and will fail to boot without it. Urbit usually only uses a portion of this, so

26it's possible to use a swap file to makeup for a shortfall without degrading

27performance. For instructions on how to configure a swap file on Linux, see

28[this linuxize.com guide](https://linuxize.com/post/create-a-linux-swap-file/).

30**A note on storage**: Urbit saves every event it processes to its [Event

31Log](https://developers.urbit.org/reference/glossary/eventlog). This means its

32disk usage slowly grows over time. Until event log truncation is implemented,

33it's advisable to have 40 or 50GB of disk space available, so you don't have to

34worry about running out for a long time. If you don't have that much, your ship

35will still run fine, but you may run out of space some months down the line.

37### 2. Install Urbit

39Choose your operating system and run the given command in your terminal to

40download the Urbit runtime, this command downloads the latest build, unpacks

41it, and runs the binary with no arguments to show you the help output:

43{% tabs %}

45{% tab label="Linux x86_64" %}

47```shell

48curl -L https://urbit.org/install/linux-x86_64/latest | tar xzk --transform='s/.*/urbit/g' && ./urbit

49```

51{% /tab %}

53{% tab label="Linux AArch64" %}

55```shell

56curl -L https://urbit.org/install/linux-aarch64/latest | tar xzk --transform='s/.*/urbit/g' && ./urbit

57```

59{% /tab %}

61{% tab label="macOS x86_64" %}

63```bash

64curl -L https://urbit.org/install/macos-x86_64/latest | tar xzk -s '/.*/urbit/' && ./urbit

65```

67{% /tab %}

69{% tab label="macOS AArch64" %}

71```bash

72curl -L https://urbit.org/install/macos-aarch64/latest | tar xzk -s '/.*/urbit/' && ./urbit

73```

75{% /tab %}

77{% /tabs %}

79If successful, you will see a block of output beginning with the line:

81```

82Urbit: a personal server operating function

83```

85### 3. Boot Urbit

87An Urbit instance is intrinsically tied to a unique identity called an **Urbit

88ID**. There are five classes of Urbit ID, but we will consider two here: comets

89and planets.

91- **Comet:** A comet is an identity which anyone can generate themselves, for

92 free. It's a good option to try out Urbit. Comets are limited by the fact they

93 cannot be "factory reset", meaning if your urbit somehow becomes broken or

94 corrupted then you'll have to start again with a new identity. In that sense,

95 they are impermanent.

97- **Planet:** A planet is a permanent identity which you own forever. Planets

98 are the class intended for individuals. While there are essentially an

99 unlimited number of comets, planets are more scarce (preventing spamming,

100 among other things). This scarcity means they usually aren't free (though

101 sometimes nice people give them away). This guide will assume you've already

102 acquired a planet. If you haven't, you can refer to the ["Get an Urbit ID"

103 guide](/getting-started/get-id) before continuing.

104

105Follow the instructions for your case:

106

107{% tabs %}

108

109{% tab label="Boot a Comet" %}

110

111In the terminal, with the `urbit` binary you installed in the previous step, a

112comet can be booted with the `-c` option:

113

114```bash

115./urbit -c mycomet

116```

117

118> `mycomet` will be the name given to the folder it will create.

119> You can choose any name you like.

120

121It may take a while to initialize the comet (usually only a couple of minutes,

122but it could take longer). When it's done, it'll take you to the dojo prompt

123(the dojo is Urbit's shell):

124

125```

126ames: live on 31337

127http: web interface live on http://localhost:8080

128http: loopback live on http://localhost:12321

129~sampel_marzod:dojo>

130```

131

132You can shut down the comet again by typing `|exit` in the dojo or hitting

133`Ctrl+D`. When it's first shut down, the runtime will be copied inside the data

134folder, so you can start it up again by doing:

135

136```bash

137./mycomet/.run

138```

139> Linux users need to run this command in another terminal window to access

140> your urbit on port 80 every time you upgrade your runtime (otherwise it'll

141> default to port 8080):

142>

143> ```shell

144> sudo apt-get install libcap2-bin

145> sudo setcap 'cap_net_bind_service=+ep' <pier>/.run

146> ```

147

148Since comets are often used temporarily and then discarded, kernel updates are

149not enabled by default. If you plan to use your comet for a while, it's a good

150idea to enable updates with the following command in the dojo:

151

152```

153|ota (sein:title our now our)

154```

155

156Lastly most people use their urbit via Landscape, the browser-based UI. In order

157to access Landscape, you need your web login code. You can get this by running

158the following command in the dojo:

159

160```

161+code

162```

163

164It'll spit out a code that'll look something like `lidlut-tabwed-pillex-ridrup`.

165Copy the code it gives you to the clipboard.

166

167{% /tab %}

168

169{% tab label="Boot a Planet" %}

170

171In order to boot a planet, you need a copy of its private keys. If you got your

172planet via a claim link, the passport backup `.zip` file you downloaded will

173contain a file called something like `sampel-palnet-1.key`. If you don't have

174the passport backup or you got your planet by another method, you can instead

175login to [Bridge](https://bridge.urbit.org/), select your planet, go to the OS

176section, and hit the "Download Keyfile" button.

177

178Back in the terminal, with the `urbit` binary you installed in the previous

179step, you can boot your planet with the following command (replacing

180`sampel-palnet` with your own planet and pointing to the location of your

181keyfile):

182

183```bash

184./urbit -w sampel-palnet -k sampel-palnet-1.key

185```

186

187This will create a folder with the name of your planet and begin booting.

188It may take a while to initialize the planet (usually only a couple of minutes,

189but it could take longer). When it's done, it'll take you to the dojo prompt

190(the dojo is Urbit's shell):

191

192```

193ames: live on 31337

194http: web interface live on http://localhost:8080

195http: loopback live on http://localhost:12321

196~sampel-palnet:dojo>

197```

198

199You can shut down the planet again by typing `|exit` in the dojo or hitting

200`Ctrl+D`. When it's first shut down, the runtime will be copied inside the data

201folder, so you can start it up again by doing:

202

203```bash

204./sampel-palnet/.run

205```

206> Linux users need to run this command in another terminal window to access

207> your urbit on port 80 every time you upgrade your runtime (otherwise it'll

208> default to port 8080):

209>

210> ```shell

211> sudo apt-get install libcap2-bin

212> sudo setcap 'cap_net_bind_service=+ep' <pier>/.run

213> ```

214

215Most people use their urbit via Landscape, the browser-based UI.

216In order to access Landscape, you need your web login code.

217You can get this by running the following command in the dojo:

218

219```

220+code

221```

222

223It'll spit out a code that'll look something like `lidlut-tabwed-pillex-ridrup`

224(note this is a separate code to your master ticket). Copy the code it gives you

225to the clipboard.

226

227One last thing: The `sampel-palnet-1.key` keyfile is only needed once, when you

228first boot your planet. **Now that it's booted, it's good security practice to

229delete that keyfile.**

231{% /tab %}

233{% /tabs %}

235### 4. Login

237While your urbit is running, the web interface called *Landscape* can be

238accessed in the browser. Its URL will usually be either `localhost` or

239`localhost:8080`, depending on your platform. To check the address, you can look

240at the boot messages in the terminal. You should see a line like:

241

242```

243http: web interface live on http://localhost:8080

244```

245

246Whichever address and port it says there is the one to open in the browser.

247

248Once open, you'll be presented with the login screen. Paste in the web login

249code you copied from the dojo in the previous step and hit "continue". You'll

250now be taken to your homescreen, with tiles for the default apps such as Groups,

251Talk, and Terminal.

252

253### 5. Runtime Upgrades

254

255When new versions of the Urbit runtime (Vere) are available, you'll have to

256shutdown your urbit and then run the `next` command in order to upgrade.

257```

258:dojo> |exit

259<pier>/.run next

260```

261Note that `<pier>` in this case is the folder that was created when you first booted

262your urbit. When you run this command your urbit will download the latest binary

263and place it inside the `.bin` directory inside your pier folder. You can then

264start your ship with the following and you'll be on the latest runtime version:

265```

266<pier>/.run

267```

268> Linux users need to run this command in another terminal window to access

269> your urbit on port 80 every time you upgrade your runtime (otherwise it'll

270> default to port 8080):

271>

272> ```shell

273> sudo apt-get install libcap2-bin

274> sudo setcap 'cap_net_bind_service=+ep' <pier>/.run

275> ```

276

277If you've been running Urbit for a while (from before runtime version 1.9)

278and these `.run` commands don't work for you, it probably means you need to

279[dock](https://operators.urbit.org/manual/running/vere#dock) your pier.

280You can do this with the following command:

281```

282./urbit dock <pier>

283```

284Then `.run` should work as expected and future runtime upgrades can be done via

285`next`.

286

287## Next steps

288

289Learn how to [get around your

290urbit](/getting-started/getting-around).